Claude Senator MCP Server

claude-senator-mcp

❌ under construction: This project is under heavy construction and is not intended for public use / nor has it been published to npm. Information in the README below may be outdated, user discretion is advised.

A Model Context Protocol (MCP) server for inter-Claude communication and context sharing. Enables Claude instances to collaborate, share context, and fork conversations without interruption.

Philosophy

Simple for humans, rich for Claude.

• Human: One-line commands that expand into ultra-rich context
• Claude: Dense collaboration intelligence with smart pointers
• Architecture: Zero-dependency file-based IPC with beautiful ASCII UI

Install

Requirements:

• Claude Code

npm install -g claude-senator

From shell:

claude mcp add claude-senator -- npx claude-senator

From inside Claude (restart required):

Add this to our global mcp config: npx claude-senator

From any manually configurable mcp.json: (Cursor, Windsurf, etc.)

{
  "mcpServers": {
    "claude-senator": {
      "command": "npx",
      "args": ["claude-senator"],
      "env": {}
    }
  }
}

Features

🏛️ **Current: Inter-Claude Messaging System**

**3-Function Interface**

# Share context with other Claude instances
claude-senator send_context --target_pid 98471 --context_request "Help with documentation"

# Receive context from other Claude instances
claude-senator receive_context

# Live status of all Claude instances with collaboration recommendations
claude-senator status

**Smart Pointer Architecture**

Ultra-lightweight context sharing using pointers to existing ~/.claude/projects/ data rather than copying content:

// Instead of copying data (expensive)
const heavyMessage = {
  conversationHistory: [
    /* 1000s of messages */
  ],
  fileContents: [
    /* large file contents */
  ],
};

// We use smart pointers (lightweight)
const smartMessage = {
  ctx_pointers: {
    projects_dir: `~/.claude/projects/${projectEncoded}`,
    conversation_history: this.getConversationPointer(),
    git_context: this.getGitContextString(),
    active_files: this.getActiveFilesArray(),
  },
};

**Beautiful ASCII UI**

╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ → Claude 98471 • "Help with documentation..." • ~/.claude pointers sent
║ 🔄 Context shared • Ready for collaboration
╚═ 🚀 2 contexts processed • Rich collaboration network active

🔄 **New: Context Forking System**

**Problem**

You have Claude deep in work (318s, 9.3k tokens) and want to ask questions without interrupting.

**Solution**

Context forking creates new Claude instances with inherited context while preserving the working Claude's state.

# Fork context from working Claude
claude-senator fork_claude --source_pid 98471 --query "What's the documentation structure?"

# Result: New session with full context + your question
# Working Claude continues uninterrupted

Technical Architecture

**Directory Structure**

/tmp/claude-senator/
├── instances/          # Each Claude writes {pid}.json with status/info
├── messages/           # Individual message files in JSONL format
└── commands/           # Command injection files for input manipulation

**Smart Pointer System**

References existing ~/.claude/projects/ data instead of copying:

interface ContextPointers {
  projects_dir: string; // `~/.claude/projects/${encoded_path}`
  conversation_history: string; // Recent conversation file path
  git_context: string; // Compact git state (branch@commit+dirty)
  active_files: string[]; // Recently modified files
  current_task: string; // What Claude is working on
  collaboration_intent: string; // Why reaching out to other Claude
}

**Message Format**

Ultra-dense messaging with context reconstruction:

interface InterClaudeMessage {
  id: string;
  from: number; // Sender Claude PID
  to: number | 'all'; // Target Claude PID or broadcast
  type: 'ultra_dense_message';
  content: string; // Human-readable request
  timestamp: number;
  options: {
    claudeContext: {
      h: string; // Human message
      pid: number; // Claude PID
      ts: number; // Timestamp
      cwd: string; // Working directory
      ctx_pointers: ContextPointers; // Smart pointers to data