Commonwealth

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:

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:

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).

1. 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.

1. 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:

commonwealth init --agent codex
commonwealth init --agent both

You can also install either plugin directly — the repo is its own compatible marketplace:

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:

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:

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):

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:

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:

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:

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:

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:

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.

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
• Source: kristoffeys/commonwealth
• License: Apache-2.0
• Homepage: https://kristoffeys.github.io/commonwealth/

Install and usage instructions live in the source repository linked above.