CollabMCP

Shared, real-time context for every Claude Code on your team — scope awareness, prior decisions, and anti-overlap. No database, no server to host. Just files in your repo.

When two people point Claude Code at the same repo, the agents have no idea the other exists. CollabMCP fixes that: it's a local MCP server that gives each agent a shared view of who's working on what, what's already been decided, and whether a file is "owned" by someone else right now.

Everything lives in a .collab/ directory in your repo — plain JSON and a JSONL log. No Postgres, no Redis, no embeddings.

What you get

Five tools, available to Claude Code automatically:

Tool	When Claude uses it
get_session	At the start of a session — who's active, recent decisions, your scope, unread messages
who_owns(path)	Before editing a file that might belong to a teammate
recall(query)	Before a big decision — has this already been settled?
remember(content, scope)	After an architectural decision or non-obvious fix
broadcast(message, urgency)	To warn the team about a breaking change

Plus a dynamic CLAUDE.md: a <!-- COLLAB --> block at the top of your CLAUDE.md that regenerates automatically as the team's state changes, so every agent reads the latest context.

Install

CollabMCP is distributed from source (not on npm). Install it once, globally:

git clone https://github.com/BautistaPessagno/collab-mcp.git
cd collab-mcp
npm install
npm run build
npm link        # makes the `collab-mcp` command available everywhere

After npm link, collab-mcp and npx collab-mcp both resolve to your local build.

Quickstart (5 steps)

Prerequisite: do the Install step once on your machine (clone + build + npm link). That's what makes the collab-mcp / npx collab-mcp command resolve — the package is not on npm.

# 1. In your project repo, initialize CollabMCP
npx collab-mcp init

# 2. Set your identity and scope
#    Edit .claude/collab.json: set "dev_id" and the "scope" globs you own
#    e.g. "dev_id": "bautista", "scope": ["/auth/**", "/middleware/**"]

# 3. Restart Claude Code so it loads the MCP server from .claude/mcp.json

# 4. Commit the shared state so teammates get it
git add .collab/state.json .collab/decisions.jsonl .claude/ CLAUDE.md
git commit -m "Add CollabMCP"

# 5. Each teammate does the Install step once (clone + build + npm link),
#    then in this repo runs `npx collab-mcp init`, sets their own
#    dev_id/scope, and restarts Claude Code. Done.

Check the team state from the terminal any time:

npx collab-mcp status

How it works

.collab/
├── state.json        # active devs, their scope, current task   (committed)
├── decisions.jsonl   # append-only log of decisions             (committed)
├── locks/            # short-lived path locks                   (gitignored)
└── inbox/            # per-dev broadcast messages               (gitignored)

• who_owns matches a path against each dev's scope globs (via minimatch) and any active lock.
• recall is keyword-overlap search over decisions.jsonl — simple, fast, no embeddings.
• A file watcher regenerates the CLAUDE.md block within ~150ms of any state change.
• Writes to state.json are atomic (temp file + rename), so concurrent devs don't corrupt it.

Config (.claude/collab.json)

{
  "server": "local",
  "collab_dir": ".collab",
  "dev_id": "bautista",
  "scope": ["/auth/**", "/middleware/**"],
  "lock_ttl_minutes": 30
}

Not in the MVP

Vector search, web dashboard, auth, Postgres/Redis, multi-repo. The data model is intentionally just files — see the roadmap in collab_mvp_plan.md.

License

MIT