Skip to main content
Glama
tmux-claude MCP Server

tmux-claude MCP Server

by michael-abdo

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

Demo 1 - Hierarchical Instance Management Hierarchical orchestration showing Executive, Manager, and Specialist instances working together

Demo 2 - Real-time Monitoring Dashboard Web-based monitoring dashboard displaying active instances and system metrics

Related MCP server: claude-code-mcp

šŸ¤– For Claude Code Instances

New to this repository? If you're a Claude Code instance, start with the Claude Getting Started Guide 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 MCP Configuration Guide 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

Available Tools

14 tools
check_workspace_conflictsC

Analyze potential conflicts in shared workspace

Inputs: workspaceDir (required), managerIds.

commit_manager_workB

Commit current work with proper git practices (Manager only)

Inputs: instanceId (required), message (required), files.

distributeWorkB

Distribute tasks across multiple Managers (Executive only)

Inputs: tasks (required), strategy.

executeParallelB

Execute multiple tasks in parallel using Specialist instances (Manager only)

Inputs: managerId (required), tasks (required), workDir (required).

getParallelStatusB

Get parallel execution status for a Manager

Inputs: managerId (required).

get_workspace_statusC

Get comprehensive status of shared workspace

Inputs: workspaceDir (required).

listB

List all active Claude instances

Inputs: role, parentId.

merge_manager_workB

Coordinate merge of manager work back to main branch (Executive only)

Inputs: managerId (required), targetBranch, strategy, deleteBranch.

readC

Read output from a Claude instance

Inputs: instanceId (required), lines, follow.

restartB

Restart a dead instance using --continue flag

Inputs: instanceId (required).

sendB

Send text/prompt to a Claude instance

Inputs: instanceId (required), text (required).

spawnB

Spawn a new Claude instance with role and context

Inputs: role (required), workDir (required), context (required), parentId, +1 more.

sync_manager_branchB

Sync manager branch with latest main branch changes (Manager only)

Inputs: instanceId (required), baseBranch.

terminateA

Terminate a Claude instance and optionally its children

Inputs: instanceId (required), cascade.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct operation: workspace management, instance lifecycle, parallel execution, and git operations. Tools like check_workspace_conflicts and get_workspace_status have clear boundaries, and even similar-sounding ones like distributeWork and executeParallel are differentiated by context (scheduling vs. running).

    Naming Consistency3/5

    The set uses a mix of snake_case (e.g., check_workspace_conflicts, commit_manager_work) and camelCase (e.g., distributeWork, executeParallel), plus short verbs (list, send, read). While each subgroup is internally consistent, the overall pattern is not uniform, which may cause slight confusion.

    Tool Count4/5

    14 tools cover the main aspects of instance management and workspace coordination without being excessive. The scope is well-defined, and each tool serves a necessary role in the multi-instance workflow.

    Completeness4/5

    The tool surface covers the key lifecycle operations (spawn, terminate, restart, send/read), parallel execution, and basic git workflow (commit, sync, merge). Minor gaps exist (e.g., no explicit tool for listing workspace files or pruning instances), but the core functionality is solid.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers