collab-mcp: Instructions file for Claude Code

CLAUDE.md — collab-mcp

Guidance for Claude Code when working on this repository (the CollabMCP tool itself).

What this is

CollabMCP is a local MCP server that gives every Claude Code on a team a shared, file-based context: scope awareness, prior decisions, and anti-overlap. The whole data model is files under .collab/ — no database, no network services.

Note: this is the source repo for the tool. The dynamic <!-- COLLAB --> block and .collab/ runtime state belong in consuming repos, not here.

Layout

src/
├── server.ts          MCP server (McpServer over stdio); registers the 5 tools
├── cli.ts             init / start / status; init writes .claude/* and the skill
├── config.ts          loads .claude/collab.json (or $COLLAB_CONFIG)
├── claude_md.ts       regenerates the COLLAB block in a consumer's CLAUDE.md
├── watcher.ts         debounced fs.watch over .collab
├── skill_template.ts  the skill text init installs into .claude/skills/collab
├── util.ts            humanAgo / minutesSince
├── types.ts           shared data shapes
├── state/
│   ├── paths.ts       canonical .collab file locations
│   ├── reader.ts      readState / readDecisions / readLocks (skips expired)
│   ├── writer.ts      atomic writes, append decisions, lock lifecycle
│   └── locks.ts       glob-based path-conflict detection (minimatch)
└── tools/             one file per tool: get_session, who_owns, remember, recall, broadcast

Conventions

• ESM + NodeNext. Relative imports must use the .js extension (e.g. import { x } from "./util.js"), even though the source is .ts.
• Tools never throw. The server wraps each handler and returns a structured { ok: false, error } payload instead. Keep that contract.
• Atomic state writes. state.json is written via temp-file + rename (writer.ts). Don't write it directly.
• Keep it file-based. No databases, embeddings, or network deps in the MVP — see collab_mvp_plan.md for what's intentionally deferred.