session-collab

Session Collab MCP

A Model Context Protocol (MCP) server for Claude Code that prevents conflicts when multiple sessions work on the same codebase simultaneously.

Problem

When using parallel Claude Code sessions or the parallel-dev workflow:

• Session A is refactoring some code
• Session B doesn't know and thinks the code "has issues" - deletes or reverts it
• Session A's work disappears

Root cause: No synchronization mechanism for "work intent" between sessions.

Solution

Session Collab MCP provides a Work-in-Progress (WIP) Registry that allows sessions to:

1. Declare - Announce which files you're about to modify
2. Check - Verify no other session is working on the same files
3. Persist - Save context that survives context compaction
4. Protect - Guard critical files from accidental changes
5. Release - Free files when done

Installation

Option 1: Claude Code Plugin (Recommended)

Install as a Claude Code plugin for automatic MCP server setup, hooks, and skills:

# Add marketplace
/plugin marketplace add leaf76/session-collab-mcp

# Install plugin
/plugin install session-collab@session-collab-plugins

The plugin includes:

• MCP Server: Automatically configured
• Hooks: SessionStart and PreToolUse reminders
• Skills: collab-start for full initialization
• Commands: /session-collab:status and /session-collab:end

Option 2: MCP Server Only

Add to your ~/.claude.json:

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

Option 3: Global Installation

npm install -g session-collab-mcp

Option 4: HTTP Server + CLI (Universal)

# Start HTTP server
session-collab-http --host 127.0.0.1 --port 8765

# CLI wrapper (HTTP client)
session-collab health
session-collab tools
session-collab call --name collab_session_start --args '{"project_root":"/repo","name":"demo"}'

Features

Automatic Session Management

Once installed, Claude will:

1. Register a session when conversation starts
2. Check for conflicts before editing files
3. Warn you if another session is working on the same files
4. Clean up when the conversation ends

Working Memory

Context persistence that survives context compaction:

• Findings: Bug root causes, investigation results
• Decisions: Architectural choices, design decisions
• State: Current implementation status
• Todos: Action items and tasks
• Important: Critical information to preserve
• Context: Background context for the session

File Protection

Guard critical files from accidental changes:

• Register protected files with reasons and priorities
• Automatic conflict detection for protected files
• Configurable protection levels

Conflict Handling Modes

Configure behavior with collab_config:

Mode	Behavior
strict	Always ask user, never bypass
smart (default)	Auto-proceed with safe content, ask for blocked
bypass	Proceed despite conflicts (warn only)

Auto-Release Options

Option	Default	Description
auto_release_immediate	false	Auto-release claims after Edit/Write
auto_release_stale	false	Auto-release claims exceeding threshold
stale_threshold_hours	2	Hours before claim is considered stale
auto_release_delay_minutes	5	Grace period for stale release

MCP Tools Reference

Session Management (5 tools)

Tool	Purpose
collab_session_start	Register a new session
collab_session_end	End session and release all claims
collab_session_list	List active sessions
collab_config	Configure session behavior
collab_status	Get session status summary

Claims (1 unified tool)

Tool	Actions
collab_claim	create, check, release, list (check: exclude_self defaults to true)

Working Memory (3 tools)

Tool	Purpose
collab_memory_save	Save context (upsert)
collab_memory_recall	Recall context
collab_memory_clear	Clear memories

Protection (1 unified tool)

Tool	Actions
collab_protect	register, check, list

Status Monitoring

Tool	Purpose
collab_status	Unified session status

HTTP API (v1)

Core endpoints map 1:1 to MCP tools: