# Commonwealth > Commonwealth: a multiplayer, git-backed, agent-readable second brain for teams - **Type:** MCP server - **Install:** `agentstack add mcp-kristoffeys-commonwealth` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kristoffeys](https://agentstack.voostack.com/s/kristoffeys) - **Installs:** 0 - **Category:** [Communication](https://agentstack.voostack.com/c/communication) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [kristoffeys](https://github.com/kristoffeys) - **Source:** https://github.com/kristoffeys/commonwealth - **Website:** https://kristoffeys.github.io/commonwealth/ ## Install ```sh agentstack add mcp-kristoffeys-commonwealth ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Commonwealth — a multiplayer second brain for teams > The shared, agent-readable context every teammate's AI reads _before_ it acts. > Instant onboarding. Anti-bus-factor. Plain markdown. Git-backed. Open source. [](LICENSE)  Published on npm as `@cmnwlth/*`. Most teams have a personal-notes story (Obsidian, `CLAUDE.md`) and an enterprise-search story (Glean, Notion AI). Nothing in between owns the **reasoning layer** of a small team — the _why_ behind decisions, the current work-state, the memory that would otherwise walk out the door with whoever wrote it. Commonwealth is that layer, made multiplayer: - **Plain markdown, git-backed.** Your knowledge is files you own — diffable, portable, no proprietary store to be locked into. - **Per-project brains.** Each project gets its own brain (one git repo). Everyone reads and writes it through their existing AI (Claude Code and Codex). - **Agent-native.** Exposed over MCP, so a teammate's agent reads the brain before acting and writes back what it learns. - **Conflict-free by design.** One fact per file with collision-proof names, so concurrent writers merge instead of clobbering each other. - **Decisions are traced.** What was decided, when, by whom, and why — captured by default. - **Secrets never sync.** API keys, tokens, and `.env`-style secrets are detected and blocked at capture and scrubbed before commit. - **Open source**, Apache-2.0. ## How it fits together ``` Claude Code / Codex (every teammate) │ reads before acting · writes back what it learns (MCP) ▼ your brain = plain markdown in a git repo │ background sync: pull · commit · push · conflict-free merge ▼ git remote (GitHub / GitLab / your own) — the team shares it ``` ## Quick start **Requirements:** Node ≥ 22 and git. Claude Code and/or Codex for the agent experience. **See it in 60 seconds, no setup:** ```bash npx @cmnwlth/cli demo ``` Scaffolds a throwaway brain for a fictional payments team and answers a few questions whose answers live only in that team's notes. It cleans up after itself (`--keep` to poke around). **Set up a brain for your project — one command:** ```bash npm i -g @cmnwlth/cli # or run any command with: npx @cmnwlth/cli cd your-project commonwealth init ``` `init` is an interactive wizard (press Enter to accept each default). It: 1. Creates a brain for this project — or **joins** the one it already belongs to. 2. Lets you multi-select which folders to sync into the brain and which repos to **seed** from (mining git history, ADRs, and agent config like `CLAUDE.md` / `.cursorrules` / `AGENTS.md`). 3. Installs the Commonwealth **plugin** for the selected agent. Claude Code and Codex both get MCP plus host-specific lifecycle hooks; Codex also gets a generated `AGENTS.md` brain snapshot. 4. Sets up your capture scope. Sync then runs **automatically in the session lifecycle** — the plugin hooks commit/pull/push at session start and after each capture, no background service required (ADR-0032). A resident daemon is available as an opt-in profile for continuous propagation. > After install, restart the selected agent and open a new session/thread so it loads the plugin. > In Claude Code, `/mcp` should list the `commonwealth` server. Beyond its tools (`search`, > `ask`, `read`, `remember`, …), the MCP server exposes the command set as **prompts** > (`/mcp__commonwealth__ask`, `remember`, `decide`, `recall`, `status`, `promote`) and the brain > as read-only **resources** (`commonwealth:///…` — the map, per-kind indexes, and > individual notes you can @-mention to pin into context), so Cursor/Windsurf/Zed/Claude Desktop > users get Commonwealth's verbs and browsing natively, not just Claude Code. > In Codex, run `/hooks`, review Commonwealth, and trust the current hook definitions; unreviewed > plugin hooks are skipped. The default remains Claude Code for backward compatibility. Select Codex or both explicitly: ```bash commonwealth init --agent codex commonwealth init --agent both ``` You can also install either plugin directly — the repo is its own compatible marketplace: ```bash claude plugin marketplace add kristoffeys/commonwealth claude plugin install commonwealth@commonwealth codex plugin marketplace add kristoffeys/commonwealth codex plugin add commonwealth@commonwealth ``` Prefer to run non-interactively (CI, scripting)? Pass `--yes` to use defaults + flags: ```bash commonwealth init --yes --agent both --sync ~/work/app --seed-repo ~/work/app --remote git@github.com:you/brain.git ``` When you give the brain a `--remote`, `init` (and `add`) also drop a `.github/workflows/commonwealth-ci.yml` into it: on every push/PR the brain's own repo clones itself and runs `verify-restore --from-remote`, so a corrupted note or broken supersede chain is caught at push time, naming the offending file. Pass `--no-ci` to skip it; a re-run never overwrites a workflow you've edited. Then open a Claude Code session or Codex thread in the project and ask it something your team already knows. Both hosts inject relevant brain context and capture before compaction. Claude Code captures at `SessionEnd`; Codex has no session-end event, so it performs throttled capture when an agent turn reaches `Stop`. In Codex, `Stop` is a turn boundary, not the end of the thread. ## Everyday use Once set up, talk to the brain through your AI in any session. The `commonwealth` CLI covers the rest — every command resolves the right brain from the current directory automatically: ```bash commonwealth add [--brain ] # wire another folder to the brain, in one go commonwealth registry # brain-resolution rules (see below) commonwealth status # last capture outcome + review queue + sync state commonwealth recall [--verbose] # search the brain (--verbose shows per-hit retrieval provenance) commonwealth ask [--answer] # cited retrieval; --answer synthesizes a cited answer via a headless model commonwealth reseed [] [--all] # mine repo(s) into the brain again commonwealth pending # notes awaiting review commonwealth promote | --all # approve staged notes into canon commonwealth promote --all --pr # open a brain-repo PR to review the promotion instead commonwealth reject # discard staged notes commonwealth sync once # sync now (lifecycle hooks do this automatically) commonwealth sync start|stop # opt into/out of the continuous daemon profile commonwealth service # run sync as an OS background service commonwealth health # freshness/trust score + capture coverage (what fraction of sessions land a note) commonwealth health --fail-under-capture 0.3 # exit non-zero when 7-day capture coverage is below 30% (CI/cron gate) commonwealth map # brain-at-a-glance: per-kind counts + top contributors commonwealth project list # engagement links: which sources are one project commonwealth project link # link a dev repo + business folder into one engagement commonwealth project unlink [] # undo a link (derived views only; no notes change) commonwealth project adopt [--dry-run] # promote a proven link into note frontmatter (one commit), then retire the entry commonwealth statusline [install] # ambient status line for Claude Code (see below) commonwealth graduate [--suggest] # propose facts recurring across ≥2 brains to the org-brain commonwealth doctor [--fix] # diagnose the setup + last capture outcome (reads ~/.commonwealth/capture.log) commonwealth update --agent both # update the CLI + refresh both host integrations commonwealth --version # print the installed CLI version ``` The CLI checks npm at most once a day and prints a note on stderr when a newer version is published (TTY only, never in CI; set `COMMONWEALTH_NO_UPDATE_CHECK=1` to silence it). ### Capturing decisions Decisions are first-class. Commonwealth records decisions it detects in a session automatically; to be sure a business or team decision is on the record — or to log one that never touched a coding session — use the deliberate path inside Claude Code: ``` /commonwealth:decide we're standardizing on Postgres for the ledger, not DynamoDB ``` It writes a `decision` note capturing **what** was decided, **when**, **who** decided it, and **why** — so a later reversal *supersedes* it rather than erasing the reasoning. ### Review vs. auto-promote By default, captured notes go **straight into canon** after the dedup + secret gates. To hold them in a review queue for approval instead, flip the per-brain flag (it syncs with the brain): ```bash commonwealth config set autoPromote false # require manual review commonwealth pending # see what's waiting commonwealth promote | --all # approve into canon ``` #### Review as a pull request Non-terminal teammates (designers, PMs) and teams that want an auditable trail can review promotions as a normal pull request on the brain repo instead of approving locally: ```bash commonwealth promote | --all --pr # branch + commit the canon adds, push, open a PR ``` This needs a git remote (`origin`) and the GitHub CLI (`gh`); local-only brains keep the plain `promote`. **Merging the PR is the promotion** — the adds are union-merge-safe (one fact per file, ADR-0003). **Closing it is the rejection** — nothing enters canon. Because the staging queue is per-user and gitignored (ADR-0008), the PR branch carries the canon adds only; your local staged copies are cleared automatically the next time you run `promote`/`status` after the PR merges, and no teammate's queue is ever touched. Scaffolded brains ship a commented-out `.github/CODEOWNERS` sample so a team can gate `decisions/` behind a lead's review with a one-line uncomment. ### Ambient status line Show the brain at a glance in Claude Code's status line — name, freshness score, and pending-review count — so "is it working?" and "is anything waiting for me?" are answered without running a command: ```bash commonwealth statusline install # add it to ~/.claude/settings.json (then restart Claude Code) ``` Renders e.g. `🧠 antenna · 87/100 · 3 pending · ⇅` (the `⇅` shows only when the optional sync daemon profile is live; with the default daemonless lifecycle sync it's simply omitted. `pending` shows only when the queue is non-empty). It reads a cached status the SessionEnd hook refreshes, so it stays well under the status line's per-turn latency budget — no git or index work happens on render. `commonwealth statusline uninstall` removes it; a hand-written `statusLine` is never clobbered. (Claude Code doesn't let a plugin register a main status line, so this one-time `install` writes the entry into your own settings.) ### Graduate shared knowledge to an org-brain When the same fact recurs across several project brains — a convention, a shared-infra rule — it can **graduate** to an _org-brain_ everyone reads. Graduation is opt-in and safe by default: ```bash commonwealth org-brain set ~/brains/org # designate the org-brain (once, per machine) commonwealth graduate --suggest # scan wired brains; stage recurring facts for review ``` A note is only ever considered when it carries `graduate: true`, and even then it must recur across **≥2 distinct brains** to be proposed. Candidates are **staged for manual review** in the org-brain (with `sources:` back-links to where they came from) — never auto-promoted across the trust boundary, regardless of any brain's `autoPromote`. Rejecting a candidate records a **reject-tombstone** in the org-brain, so the same cluster is not re-proposed on the next run (it is skipped with a `(previously rejected — N suppressed)` note); `commonwealth graduate --include-rejected` resurfaces them. See [ADR-0023](docs/adr/0023-org-brain-graduation.md). ### Route projects to brains (rules) Which brain a directory reads and writes is decided by an ordered **ruleset** ([ADR-0024](docs/adr/0024-rule-based-brain-resolution.md)). A rule matches by **git identity** or **path**, and routes to a brain, denies capture, or falls through to a default brain: ```bash commonwealth registry default ~/brains/antenna # the brain bare "allow" rules route to commonwealth registry allow 'org:weareantenna/*' # all repos of an org → the default brain commonwealth registry route repo:weareantenna/erp ~/brains/erp # one repo → a different brain commonwealth registry deny repo:weareantenna/secrets # never capture this repo commonwealth registry route 'path:~/scratch' ~/brains/scratch # a path (non-repo dirs, monorepos) commonwealth registry show # list rules and the default brain commonwealth registry remove repo:weareantenna/erp # drop a rule ``` **Share rules with your team** ([ADR-0024 §5](docs/adr/0024-rule-based-brain-resolution.md)). Add `--shared` and the rule lives in the brain's committed config instead of your machine-local one, so it syncs to every teammate — the `repo → brain` _intent_ is portable even though each person's brain _path_ differs: ```bash commonwealth registry route repo:weareantenna/erp ~/brains/erp --shared # the team routes erp here commonwealth registry deny repo:weareantenna/secrets --shared # a team-wide deny commonwealth registry pull # materialize teammates' shared rules ``` Shared rules are materialized into your local config automatically on `sync`; `pull` does it on demand. Your **local** rules always override a shared rule for the same matcher, so a personal deny or reroute is never clobbered by the team's — and personal (`local`, the default) rules never sync. A **matcher** is one of: | Matcher | Matches | Example | | -------------------- | -------------------------------------------------- | ----------------------------- | | `repo:` | an exact repo (by its git `origin`) | `repo:weareantenna/erp` | | `org:` | every repo of an owner | `org:weareantenna` (or `…/*`) | | `path:` | a path prefix — for non-repo dirs & monorepo subtrees | `path:~/scratch` | | `*` | everything (the catch-all) | `commonwealth registry allow '*'` | **Precedence** (most specific wins): `repo` > `org` > `path` (longest) > `*`. A **deny** wins on a tie. A bare **allow** (no brain) routes to the `default` brain; an unmatched directory captures nothing. Because `repo`/`org` match on git identity, a rule **follows a repo across every worktree, clone, and machine** — one `org:weareantenna/*` line covers all of Antenna's repos and all their branch worktrees, which path prefixes never could. Quote matchers containing `*` so your shell doesn't expand them. > `commonwealth add ` writes a rule for you: a `repo:` rule when the folder is a git repo with an `origin` (so it follows that repo everywhere), otherwise a `path:` rule. ### Keep personal projects out (scope) A per-user, local allow/deny list decides which folders are ever captured or injected — personal projects stay out. It lives in `~/.commonwealth/config.json` and is never synced. ```bash commonwealth scope allow ~/work # only capture work under here… commonwealth scope deny ~/work/secret # …except this (deny wins) commonwealth scope check # → in-scope | out-of-scope (for the cwd) ``` Rule: in scope if `(allow is empty OR under an allow entry) AND under no deny entry`. With no config, everything is in scope; add a deny (or a narrow allow) to exclude. Scope only decides *whether* capture may happen in a folder — *which brain* the folder writes to is a separate mapping. To bring a new … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [kristoffeys](https://github.com/kristoffeys) - **Source:** [kristoffeys/commonwealth](https://github.com/kristoffeys/commonwealth) - **License:** Apache-2.0 - **Homepage:** https://kristoffeys.github.io/commonwealth/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-kristoffeys-commonwealth - Seller: https://agentstack.voostack.com/s/kristoffeys - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.