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:

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.

Related MCP server: Twining MCP Server

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