Skip to content

Quickstart

Get a Commonwealth brain running for one project in a couple of minutes, from npm.

Prerequisites

  • Node ≥ 22 and git on your PATH (a brain is a git repo).
  • Optionally, the claude CLI (Claude Code) for automatic session capture via the plugin.

0. Try it with no setup (optional)

npx @cmnwlth/cli demo

Scaffolds a throwaway brain for a fictional team and answers questions whose answers live only in its notes, then cleans up after itself (--keep to poke around the files first).

1. Install the CLI

npm i -g @cmnwlth/cli      # or run any command with: npx @cmnwlth/cli <command>

2. Initialize a brain for your project

From the project you want a brain for:

cd ~/work/my-project
commonwealth init

One idempotent command does the whole setup: creates a brain repo (a separate git repo under ~/.commonwealth/brains/<project>), registers this project → that brain, seeds it by mining your git history / ADRs / agent config into the review queue, installs the Commonwealth plugin (MCP + session hooks), starts the sync daemon, and ensures your per-user scope config exists. Re-run it anytime — it only does what's still missing. See the flags in commonwealth init --help (e.g. --yes, --no-daemon, --no-seed, --brain <dir>, --remote <url>).

Prefer to install just the Claude Code plugin (the repo is its own plugin marketplace)?

claude plugin marketplace add kristoffeys/commonwealth
claude plugin install commonwealth@commonwealth

3. Use it

  • In a Claude Code session in this project, the plugin injects relevant team-brain context at session start and captures durable knowledge at session end (subject to the scope + curation gates). Ask it something your project already knows.
  • From the CLI:
commonwealth status        # review queue + sync-daemon state
commonwealth recall <q>    # search the brain
commonwealth ask <q>       # a cited answer synthesized from the brain
commonwealth health        # freshness/trust score (stale / unverified / orphaned counts)
commonwealth pending       # notes awaiting review (when autoPromote is off)
commonwealth promote --all # approve staged notes into canon

The MCP server also exposes search, read, remember, list-work-state, and who-is to any MCP client.

What just happened

  • Your notes are plain markdown in the brain repo — the source of truth. Any index/DB is derived and rebuildable.
  • Captured knowledge passes the scope + dedup + secret gates before it lands. By default (autoPromote) it goes straight to canon; set the flag off to require manual review.

Next: Self-host guide — share a brain across a team with a git remote.