claude-senator-mcp by Vvkmnn - 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
    };
  };
}

Implementation Details

Current Messaging System

SessionManager Core Methods

`createMessage(humanMessage: string)`

Creates ultra-dense context messages with smart pointers:

Purpose: Lightweight context sharing
Input: Human message string
Output: Smart pointer context object with collaboration intelligence
Used by: send_context tool

private createMessage(humanMessage: string): any {
  const workingDir = process.cwd();
  const claudeDir = join(homedir(), '.claude');
  const projectEncoded = workingDir.replace(/\//g, '-').replace(/^-/, '');
  const pid = process.ppid || process.pid;

  return {
    h: humanMessage,
    pid: pid,
    ts: Date.now(),
    cwd: workingDir,
    ctx_pointers: {
      projects_dir: `~/.claude/projects/${projectEncoded}`,
      conversation_history: this.getConversationPointer(),
      git_context: this.getGitContextString(),
      active_files: this.getActiveFilesArray(),
      current_task: this.getCurrentTaskFromContext(),
      collaboration_intent: this.determineCollaborationIntent(humanMessage)
    }
  };
}

`reconstructRichContext(message: any)`

Rebuilds full context from smart pointers:

Purpose: Context reconstruction on receiving end
Input: Message with smart pointers
Output: Full context object with conversation history
Used by: receive_context tool

private reconstructRichContext(message: any): any {
  const ctx = message.options?.claudeContext;
  if (!ctx?.ctx_pointers) return null;

  const pointers = ctx.ctx_pointers;
  const reconstructed = {
    sender_info: {
      human_message: ctx.h,
      pid: ctx.pid,
      working_directory: ctx.cwd,
      timestamp: ctx.ts
    },
    collaboration_context: {
      current_task: pointers.current_task,
      intent: pointers.collaboration_intent,
      git_state: pointers.git_context,
      active_files: pointers.active_files
    },
    shared_data_access: {
      projects_dir: pointers.projects_dir,
      conversation_history: pointers.conversation_history
    }
  };

  // Load conversation history if pointer exists
  if (pointers.conversation_history) {
    reconstructed.conversation_snippet = this.loadConversationSnippet(pointers.conversation_history);
  }

  return reconstructed;
}

`generateRichContextDisplay(instance: any, activity: any)`

Creates real-time status with collaboration scoring:

Purpose: Live context display without transmission
Input: Claude instance data and activity
Output: Rich context with collaboration readiness score
Used by: status tool

private generateRichContextDisplay(instance: any, activity: any): any {
  const workingDir = instance.cwd || instance.projectPath || '/unknown';
  const encodedPath = String(workingDir).replace(/\//g, '-').replace(/^-/, '');

  const contextPointers = {
    projectsDir: `~/.claude/projects/${encodedPath}`,
    conversationHistory: this.getConversationPointer(workingDir),
    gitContext: this.getGitContextString(workingDir),
    activeFiles: this.getActiveFilesArray(workingDir),
    currentTask: activity.task || 'Active',
    collaborationIntent: this.determineCollaborationReadiness(activity, instance)
  };

  const collaborationMetrics = {
    hasRecentActivity: activity.lastActivity > Date.now() - 300000,
    hasActiveFiles: contextPointers.activeFiles.length > 0,
    hasCleanGitState: !contextPointers.gitContext.includes('dirty'),
    isWorkingOnKnownTask: activity.task && activity.task !== 'Active',
    projectType: this.detectProjectType(workingDir)
  };

  return {
    ...contextPointers,
    collaborationMetrics,
    collaborationReason: this.getCollaborationReason(collaborationMetrics),
    readinessScore: this.calculateReadinessScore(collaborationMetrics)
  };
}

Collaboration Scoring Algorithm

private calculateCollaborationScore(contextData: any): number {
  const metrics = contextData.collaborationMetrics;
  if (!metrics) return 0;

  let score = 0;
  if (metrics.hasRecentActivity) score += 0.3;
  if (metrics.hasActiveFiles) score += 0.2;
  if (metrics.hasCleanGitState) score += 0.2;
  if (metrics.isWorkingOnKnownTask) score += 0.2;
  if (metrics.projectType !== 'unknown') score += 0.1;

  return Math.min(score, 1.0);
}

Context Pointer Helpers

private getConversationPointer(): string | null {
  const claudeDir = join(homedir(), '.claude');
  const projectEncoded = process.cwd().replace(/\//g, '-').replace(/^-/, '');
  const projectDir = join(claudeDir, 'projects', projectEncoded);

  if (existsSync(projectDir)) {
    const files = readdirSync(projectDir).filter(f => f.includes('conversation'));
    if (files.length > 0) {
      return `~/.claude/projects/${projectEncoded}/${files[files.length - 1]}`;
    }
  }
  return null;
}

private getGitContextString(): string {
  try {
    const branch = execSync('git branch --show-current 2>/dev/null', { encoding: 'utf8' }).trim();
    const commit = execSync('git rev-parse --short HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
    const status = execSync('git status --porcelain 2>/dev/null', { encoding: 'utf8' }).trim();
    const dirty = status ? '+dirty' : '';
    return `${branch}@${commit}${dirty}`;
  } catch (error) {
    return 'no-git';
  }
}

private getActiveFilesArray(): string[] {
  try {
    const recentFiles = execSync('git diff --name-only HEAD~1 2>/dev/null', {
      encoding: 'utf8'
    }).trim().split('\n').filter(f => f);
    return recentFiles.slice(0, 5);
  } catch (error) {
    return [];
  }
}

New Context Forking System

Core Implementation

// New MCP tool
{
  name: 'fork_claude',
  description: 'Create new Claude session with full context from target Claude',
  inputSchema: {
    source_pid: { type: 'number', description: 'Claude to copy from' },
    query: { type: 'string', description: 'Your question for the new Claude' }
  }
}

// Implementation
case 'fork_claude': {
  const sourcePid = args?.source_pid as number;
  const query = args?.query as string;

  // Find source Claude's conversation
  const sourceActivity = this.sessionManager.parseLiveActivity(sourcePid);
  const conversationPath = this.findConversationPath(sourcePid);

  // Copy conversation to new session
  const newSessionId = this.createForkedSession(conversationPath, query);

  return {
    content: [{
      type: 'text',
      text: `╔═ 🔄 Context Forked ═══════════════════════════════════════════════════
║ 📸 Copied: ${sourceActivity.task} • Full conversation history
║ 🆕 New session: ${newSessionId}
║ 🎯 Ready for: "${query}"
╚═ ✨ Run: claude --session ${newSessionId} to start new Claude with context`
    }]
  };
}

Session Creation

private createForkedSession(sourcePath: string, newQuery: string): string {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '');
  const newSessionId = `fork_${timestamp}`;
  const newSessionPath = join(homedir(), '.claude', 'sessions', newSessionId);

  // Create new session directory
  mkdirSync(newSessionPath, { recursive: true });

  // Copy conversation history
  if (existsSync(sourcePath)) {
    const conversationContent = readFileSync(sourcePath, 'utf8');
    const newConversationPath = join(newSessionPath, 'conversation.jsonl');
    writeFileSync(newConversationPath, conversationContent);

    // Add new query as next message
    const queryMessage = {
      type: 'user',
      message: { content: newQuery },
      timestamp: Date.now()
    };

    appendFileSync(newConversationPath, '\n' + JSON.stringify(queryMessage));
  }

  return newSessionId;
}

Usage Examples

Basic Messaging Workflow

# 1. Check who's available for collaboration
claude-senator status

# Output:
╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ 3 Claudes active • rich context network
║ 🟢 Claude 98471 • rust-project • debugging memory leak • main@a1b2c3
╚═ 🔄 Live status • Smart pointer network active

# 2. Send context to specific Claude
claude-senator send_context --target_pid 98471 --context_request "Need help with async Rust debugging"

# Output:
╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ → Claude 98471 • "Need help with async Rust debugging" • ~/.claude pointers sent
║ 🔄 Context shared • Ready for collaboration
╚═ 🚀 Context transmitted • Collaboration network active

# 3. Receive context from other Claudes
claude-senator receive_context

# Output:
╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ "Debug memory leak in tokio runtime" • debugging_assistance • rust-project
║ 📊 Rich context: git state, active files, current task
╚═ 📨 1 context processed • Ready for collaboration

Context Forking Workflow

# Scenario: Claude deep in documentation work, want to ask questions
claude-senator status

# Output shows Claude 98471 working on documentation (318s, 9.3k tokens)
╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ 1 Claude active • rich context network
║ 🟡 Claude 98471 • docs-project • Writing API documentation • main@x1y2z3
╚═ 🔄 Live status • Smart pointer network active

# Fork context without interrupting
claude-senator fork_claude --source_pid 98471 --query "What's the current API documentation structure?"

# Output:
╔═ 🔄 Context Forked ═══════════════════════════════════════════════════════
║ 📸 Copied: Writing API documentation • 9.3k tokens • Full conversation
║ 🆕 New session: fork_20250716_141509
║ 🎯 Ready for: "What's the current API documentation structure?"
╚═ ✨ Run: claude --session fork_20250716_141509 to start new Claude

# Start new Claude with inherited context
claude --session fork_20250716_141509
# New Claude starts with full context + your question already asked

Architecture Benefits

Zero Dependencies

No npm packages beyond @modelcontextprotocol/sdk
No external services (Redis, databases, etc.)
No system dependencies
No elevated permissions

Token Efficiency

Smart pointers prevent data duplication
Context reconstruction on-demand
Minimal memory footprint
Efficient git state tracking

Scalability

2-20 Claudes: Excellent performance (<10ms operations)
20-100 Claudes: Good performance, minimal filesystem overhead
100+ Claudes: May benefit from SQLite upgrade (see Future section)

Reliability

Each Claude owns its files (no shared writes)
Automatic cleanup of dead instances
Graceful error handling
Self-healing directory structure

UI Design Philosophy

3-Line ASCII Format

╔═ 🏛️ ═══════════════════════════════════════════════════════════════════
║ [CONTENT LINE - exactly fits terminal width]
║ [STATUS LINE - shows current state and metrics]
╚═ [FOOTER LINE - shows next action or network status]

Truncation Rules

Content truncated to fit terminal width
Important information prioritized
Emoji indicators for quick scanning
Consistent spacing and alignment

Tool-Specific Emoji

🏛️ Always at top (Claude Senator identity)
🔄 Context sharing operations
📨 Message receiving
🔄 Context forking
🚀 Network activity

File Structure

Core Files

src/
├── index.ts          # MCP server and tool handlers
├── session.ts        # SessionManager - core messaging logic
├── memory.ts         # MemoryManager - conversation search
├── injection.ts      # CommandInjector - input manipulation
└── types.ts          # TypeScript interfaces

Key Classes

SessionManager (src/session.ts)

Purpose: Core messaging and context management
Key methods: createMessage, reconstructRichContext, generateRichContextDisplay
Handles: Smart pointers, context reconstruction, collaboration scoring

MemoryManager (src/memory.ts)

Purpose: Conversation history search and analysis
Key methods: TBD (future implementation)
Handles: Historical context retrieval, memory patterns

CommandInjector (src/injection.ts)

Purpose: Input manipulation and command routing
Key methods: TBD (future implementation)
Handles: Inter-Claude command injection, workflow automation

Future Enhancements

Messaging System Extensions

// Planned tools
{
  name: 'broadcast_context',
  description: 'Send context to all active Claude instances'
}

{
  name: 'handoff_context',
  description: 'Transfer work to another Claude with full context'
}

{
  name: 'sync_context',
  description: 'Synchronize context across multiple Claude instances'
}

Context Forking Improvements

// Selective inheritance
{
  name: 'fork_claude_selective',
  inputSchema: {
    source_pid: number,
    query: string,
    include_conversation: boolean,
    include_files: boolean,
    include_git_state: boolean
  }
}

// Context merging
{
  name: 'merge_context',
  description: 'Merge insights from forked Claude back to parent'
}

Performance Optimizations

Context Caching: LRU cache for frequently accessed contexts
Compression: Gzip compression for large conversation histories
Streaming: Real-time context updates as work progresses
SQLite Upgrade: For 100+ concurrent Claude instances

Integration Possibilities

IDE Plugins: VS Code, Cursor, Windsurf integration
CI/CD: Automated context sharing in build pipelines
Monitoring: Real-time collaboration network visualization
Analytics: Context sharing patterns and optimization

Project Split Guide

If splitting into separate projects:

Core Messaging (claude-senator-messaging)

Files: src/session.ts (lines 1-883, 1075-1451), src/types.ts
Dependencies: src/memory.ts for conversation search
Features: send_context, receive_context, status
Size: ~1400 lines, full messaging system

Context Forking (claude-senator-forking)

Files: New implementation in src/forking.ts
Dependencies: src/session.ts (conversation finding methods)
Features: fork_claude tool
Size: ~50 lines, minimal implementation

Shared Infrastructure (claude-senator-core)

Files: src/types.ts, directory management utilities
Purpose: Common interfaces and utilities
Size: ~200 lines, essential types and helpers

Migration Strategy

Extract core types: Move interfaces to shared package
Split session manager: Separate messaging and forking logic
Maintain compatibility: Ensure both systems can coexist
Document interfaces: Clear APIs for integration

Development

git clone https://github.com/yourusername/claude-senator
cd claude-senator
npm install
npm run build
npm test

Contributing

Fork the repository and create feature branches
Test with multiple Claude instances before submitting PRs
Follow TypeScript strict mode and MCP protocol standards
Document any new smart pointer patterns

Testing

Test messaging between 2-5 Claude instances
Verify context reconstruction accuracy
Test forking with large conversation histories
Validate ASCII UI formatting across terminals

License

Claude Senator enables unprecedented collaboration between Claude instances through smart context sharing and non-disruptive forking. Built for developers who need their AI assistants to work together as seamlessly as they do.