michael-abdo/tmux-claude-mcp-server

tmux-claude MCP Server

A highly efficient Model Context Protocol (MCP) server enabling hierarchical orchestration of Claude instances via tmux. Features a bridge pattern architecture that reduces memory usage by 85% compared to traditional multi-server approaches.

📸 Screenshots

Hierarchical orchestration showing Executive, Manager, and Specialist instances working together

Web-based monitoring dashboard displaying active instances and system metrics

🤖 For Claude Code Instances

New to this repository? If you're a Claude Code instance, start with the for a quick orientation and practical examples.

Overview

Architecture Innovation

Due to MCP's documented 1:1 stdio architecture, multiple Claude instances cannot directly access MCP tools. Our bridge pattern solution:

• Single shared MCP server process (50-70MB total)
• Lightweight bridge for multi-instance access via Bash
• 85% memory reduction vs spawning separate servers
• Zero race conditions with centralized state management

Core MCP Tools

• spawn: Create new Claude instances with roles (Executive/Manager/Specialist)
• send: Send text/prompts to instances
• read: Read output from instances
• list: List active instances with filtering
• terminate: Stop instances and optionally their children

New Features

• VM Integration: Complete cloud VM management for development environments
• Scheduled Continue: Schedule "Plz continue" messages to all tmux sessions at specified times
• Workspace Modes: Support for isolated (default) and shared workspace modes
• Git Integration: Automatic branch management for shared workspaces
• Conflict Detection: Proactive identification of merge conflicts
• MCP Git Tools: 5 new tools for git operations (git_status, git_branch, etc.)
• AI Conflict Resolution: Intelligent merge conflict resolution using Claude
• Performance Optimizations: Parallel spawning, message batching, caching
• Monitoring Dashboard: Real-time web dashboard for system monitoring

Project Structure

tmux-claude-mcp-server/
├── README.md              # Project overview and usage
├── LICENSE                # MIT license
├── package.json           # Node.js dependencies
├── package-lock.json      # Locked dependencies
├── .gitignore            # Version control ignore patterns
├── src/                   # Core source code
│   ├── simple_mcp_server.js    # Main MCP server
│   ├── instance_manager.js     # Instance lifecycle management
│   ├── mcp_tools.js            # MCP tool implementations
│   ├── tmux_interface.js       # tmux integration layer
│   ├── reliable_tmux_sender.js # High-reliability message delivery
│   ├── orchestration/          # Orchestration components
│   ├── dashboard/              # Web monitoring dashboard
│   ├── role_templates/         # Standardized role templates
│   └── workflow/               # Workflow orchestration system
│       ├── actions/            # Modular action implementations
│       ├── workflow_engine.cjs # Main workflow engine
│       └── run_workflow.cjs    # Workflow runner CLI
├── scripts/               # Utility scripts
│   ├── mcp_bridge.js           # Bridge for multi-instance MCP access
│   ├── scheduled_continue.js   # Schedule "Plz continue" messages
│   ├── check/                  # Session checking utilities
│   ├── restart/                # Session restart utilities
│   ├── utils/                  # Shared utilities
│   │   └── time_parser.js     # Time parsing for scheduling
│   └── api/                    # API scripts for monitoring
├── docs/                  # Documentation
│   ├── CHANGELOG.md             # Version history
│   ├── CONTRIBUTING.md          # Contribution guidelines
│   ├── WORKFLOW_GUIDE.md        # Workflow system guide
│   ├── CLAUDE_GETTING_STARTED.md    # Quick start for Claude instances
│   ├── DOCUMENTATION_INDEX.md       # Documentation map
│   ├── scheduled_continue/          # Scheduled continue feature docs
│   │   ├── CLI_INTERFACE_DESIGN.md
│   │   ├── TIME_FORMAT_SPECIFICATION.md
│   │   └── SCHEDULING_MECHANISM_ANALYSIS.md
│   ├── analysis/          # Technical analysis & findings
│   ├── archive/           # Historical documentation
│   └── guides/            # User guides and specifications
├── tests/                 # Test suites
│   ├── test_workflow_standalone.cjs  # Standalone workflow tests
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   ├── e2e/              # End-to-end tests
│   └── performance/      # Performance benchmarks
├── workflows/             # Workflow system
│   ├── README.md              # Workflow documentation
│   ├── CURRENT_STATUS.md      # Current status and usage
│   ├── library/               # Reusable workflow components
│   ├── examples/              # Example workflows
│   ├── tests/                 # Workflow test files
│   ├── scripts/               # Workflow utilities
│   ├── state/                 # Workflow state storage
│   └── user/                  # User-created workflows
├── state/                # Default state directory
├── config/               # Configuration files
├── logs/                 # Log directory
└── vm-integration/       # Cloud VM management
    ├── README.md              # VM integration documentation
    ├── vm_manager.js          # Core VM management class
    ├── vm_cli.js              # Command-line interface
    ├── vm_mcp_tools.js        # MCP tools integration
    ├── integrate_vm_mcp.js    # MCP server integration
    ├── setup-scripts/         # VM initialization scripts
    │   └── claude-dev-setup.sh
    └── tests/                 # VM integration tests
        └── test_vm_integration.js

Architecture

• External State Store: JSON file-based registry for Phase 1, Redis-ready for Phase 2+
• Project Isolation: Each Claude instance uses --project flag for conversation isolation
• Role-Based Access: Specialists have NO access to MCP tools, only Executive/Manager can orchestrate
• Hierarchical Naming: exec_1, mgr_1_1, spec_1_1_1 for clear parent-child relationships
• Nearly-Free Recovery: Restart instances using --continue flag

Code Harvest

This implementation harvests and adapts ~20-30% of the existing tmux-manager codebase:

Harvested Components

• tmux_interface.py → src/tmux_interface.js - Core tmux operations
• instance.py → src/instance_manager.js - Instance lifecycle management
• manager.py → src/instance_manager.js - Registry and coordination
• session_manager.py → src/instance_manager.js - Session operations

Discarded Components (60-70%)

• All CLI interfaces
• Pattern matching/monitoring systems
• Event bus architecture
• Configuration management
• Layout systems

Installation

cd tmux-claude-mcp-server
npm install

Configuration (REQUIRED)

CRITICAL: You MUST configure the MCP server globally for all Claude instances:

claude mcp add tmux-claude -s user node /path/to/tmux-claude-mcp-server/src/simple_mcp_server.js

Important notes:

• The -s user flag is REQUIRED for hierarchical orchestration to work
• This makes the MCP server available to ALL Claude instances
• Without this, spawned instances will NOT have access to MCP tools
• See for detailed information

Verify configuration:

claude mcp list
# Should show: tmux-claude: node /path/to/simple_mcp_server.js

Usage

The MCP server runs automatically when Claude starts (after proper configuration above).

Tool Examples

Spawn an Executive

{
  "name": "spawn",
  "arguments": {
    "role": "executive",
    "workDir": "/jobs/auth_system",
    "context": "# Executive: Auth System\\n\\nYou are responsible for orchestrating the implementation of a JWT authentication system..."
  }
}

Executive Spawns Manager

{
  "name": "spawn", 
  "arguments": {
    "role": "manager",
    "workDir": "/jobs/auth_system",
    "context": "# Manager: Auth Implementation\\n\\nPlan and coordinate the JWT auth system implementation...",
    "parentId": "exec_1"
  }
}

Manager with Shared Workspace (NEW)

{
  "name": "spawn",
  "arguments": {
    "role": "manager",
    "workDir": "/jobs/auth_system", 
    "context": "# Manager: Feature Implementation\\n\\nCoordinate multiple specialists...",
    "parentId": "exec_1",
    "workspaceMode": "shared"  // Enable git integration
  }
}

Manager Spawns Specialist

{
  "name": "spawn",
  "arguments": {
    "role": "specialist", 
    "workDir": "/jobs/auth_system",
    "context": "# Specialist: User Model\\n\\nImplement the User model with Mongoose...",
    "parentId": "mgr_1_1"
  }
}

Send Task to Specialist

{
  "name": "send",
  "arguments": {
    "instanceId": "spec_1_1_1",
    "text": "Please implement the User model with email, password, and timestamps fields"
  }
}

Read Specialist Output

{
  "name": "read",
  "arguments": {
    "instanceId": "spec_1_1_1",
    "lines": 50
  }
}

List All Active Instances

{
  "name": "list",
  "arguments": {}
}

List Manager's Specialists

{
  "name": "list",
  "arguments": {
    "parentId": "mgr_1_1"
  }
}

Terminate Completed Specialist

{
  "name": "terminate",
  "arguments": {
    "instanceId": "spec_1_1_1"
  }
}

State Management

External State Store (Phase 1)

Located at ./state/instances.json:

{
  "instances": {
    "exec_1": {
      "instanceId": "exec_1",
      "role": "executive",
      "parentId": null,
      "sessionName": "claude_exec_1",
      "projectDir": "/jobs/auth_system/exec_1",
      "paneTarget": "claude_exec_1:0.0",
      "status": "active",
      "created": "2024-01-01T10:00:00Z",
      "children": ["mgr_1_1"]
    }
  }
}

Instance Directory Structure

/jobs/auth_system/
├── exec_1/
│   ├── CLAUDE.md              # Executive context
│   └── project files...
├── mgr_1_1/  
│   ├── CLAUDE.md              # Manager context
│   └── project files...
└── spec_1_1_1/
    ├── CLAUDE.md              # Specialist context
    └── implementation files...

Error Recovery

The server implements nearly-free recovery using Claude's --continue flag:

{
  "name": "restart",
  "arguments": {
    "instanceId": "spec_1_1_1"
  }
}

This will:

1. Check if instance is actually dead
2. Recreate tmux session in same project directory
3. Launch claude --project . --continue
4. Claude automatically resumes where it left off

Role-Based Access Control

• Executive: Full access to all MCP tools
• Manager: Full access to all MCP tools
• Specialist: NO access to MCP tools (uses standard Claude tools only)

The server enforces this by checking the caller's role and rejecting MCP tool calls from Specialists.

Integration with Claude SDK

Each spawned instance:

• Uses --project <dir> for conversation isolation
• Gets unique project directory: ~/.claude/projects/-jobs-auth_system-<instance_id>/
• Maintains separate conversation history and todos
• Can be monitored via read-only access to Claude's todo files

Phase Evolution

• Phase 1: Sequential execution, 1 Executive → 1 Manager → 1 Specialist
• Phase 2: Limited parallelism, 2-3 Specialists per Manager
• Phase 3: Full parallelism, multiple Managers and Specialists

The MCP interface is designed to support all phases without code changes - only configuration differences.

Scheduled Continue Feature

The Scheduled Continue feature allows you to schedule "Plz continue" messages to all tmux sessions at a specified time. This is useful for automating session management and ensuring work resumes at specific times.

Basic Usage

# Schedule in 30 minutes
node scripts/scheduled_continue.js "+30m"

# Schedule at 3:30 PM today
node scripts/scheduled_continue.js "15:30"

# Schedule at 9:45 AM with AM/PM format
node scripts/scheduled_continue.js "9:45am"

# Schedule using natural language
node scripts/scheduled_continue.js "in 2 hours"

Advanced Options

# Custom message
node scripts/scheduled_continue.js "+1h" -m "Time to review progress"

# Dry run (test without executing)
node scripts/scheduled_continue.js "+5m" --dry-run

# Verbose logging
node scripts/scheduled_continue.js "+15m" --verbose

# Show help
node scripts/scheduled_continue.js --help

Supported Time Formats

• Relative: +30m, +2h, +90m
• 24-hour: 15:30, 09:45, 23:59
• 12-hour: 3:30pm, 9:45am, 11:59PM
• Natural language: "in 30 minutes", "in 2 hours"

Important Notes

• The process must remain running until execution time
• System sleep/hibernate may interrupt scheduling
• Maximum scheduling window is 24 hours
• Sessions are re-validated at execution time
• Uses high-reliability message delivery

For detailed documentation, see:

Testing

npm test                         # Run all tests
./scripts/run_all_tests.sh      # Run comprehensive test suite

Development

npm run dev  # Start with file watching

Architecture Documents

For complete implementation details, see:

• docs/main/tmux-manager-MCP.md - MCP server specification
• docs/main/tmux-claude-implementation.md - Complete architecture
• docs/main/tmux-mvp-implementation.md - Phase 1 MVP approach
• docs/GIT_INTEGRATION_GUIDE.md - Git integration and workspace modes
• docs/WORKSPACE_MODES.md - Detailed workspace mode documentation
• docs/GIT_INTEGRATION_REFINEMENT_PLAN.md - Technical implementation details