session-collab

Session Collab MCP provides a Work-in-Progress (WIP) registry that helps Claude Code sessions coordinate on the same codebase. Once the MCP server is running, you can declare which files you intend to modify, check for conflicts with other active sessions, persist relevant context across Clifford context changes, protect critical files from edits, and release files when you’re done. The server exposes a set of tools under the MCP API that handle session management, claims (for file ownership), memory (for persistent findings and decisions), protection, and status reporting. The HTTP API mapping means you can drive these capabilities through simple /v1 endpoints, making it easy to integrate with Claude Code workflows and your existing automation.

To use it effectively, start a session with collab_session_start, announce the files you’ll work on with collab_claim (action create), and periodically check for conflicts before editing with collab_claim (action check). When you’re finished, release your claims with collab_claim (action release) and end the session with collab_session_end. You can also save working context (collab_memory_save) to preserve findings and decisions, and register any protected files (collab_protect) to guard critical code paths. For HTTP usage, you can interact with the v1 endpoints such as POST /v1/sessions/start, POST /v1/claims, POST /v1/memory/save, and POST /v1/protect/register to perform these actions programmatically.

Prerequisites:

• Node.js 18+ (per project requirements)
• npm or yarn

Option A: Install as a Claude Code plugin (recommended)

• In Claude Code, add the plugin marketplace entry:
  • /plugin marketplace add leaf76/session-collab-mcp
• Then install the plugin:
  • /plugin install session-collab@session-collab-plugins

Option B: MCP Server Only (npm-based install)

• Configure in ~/.claude.json as shown in the README:

  {
    "mcpServers": {
      "session-collab": {
        "command": "npx",
        "args": ["-y", "session-collab-mcp@latest"]
      }
    }
  }
  

Option C: Global Installation (CLI available)

• Run:
  • npm install -g session-collab-mcp

Option D: HTTP API + CLI (universal method)

• Start the HTTP server (if you’re using the HTTP interface):
  • session-collab-http --host 127.0.0.1 --port 8765
• Use the CLI wrapper to call tools, e.g.:
  • session-collab health
  • session-collab tools
  • session-collab call --name collab_session_start --args '{"project_root":"/repo","name":"demo"}'

Notes:

• Ensure network access if using remote plugin hosting or a shared workspace.
• The MCP stores data locally in ~/.claude/session-collab/collab.db (SQLite).

Tips and common considerations:

• Default conflict handling is governed by collab_config (strict, smart, bypass). If you frequently work on overlapping files, consider tuning the mode to smart for automatic safe progression.
• Use collab_protect to lock down critical files early in a feature or sprint to prevent accidental edits by parallel sessions.
• When using the HTTP API, map endpoints to tools as documented to unify behavior across sessions.
• If you migrate between v1 and v2 APIs, consult MIGRATION.md for compatibility and schema changes.
• Data is stored locally; for sharing work across machines, consider a local data path that’s synchronized or a small local server with backup.
• Ensure you have the appropriate permissions to install global npm packages if using the global install option.