# 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](https://modelcontextprotocol.io) 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:

```bash
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](#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.

```bash
# 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:

```bash
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`)

```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`](./collab_mvp_plan.md).

## License

MIT