tmux-claude MCP Server
Provides MCP tools for git operations including status, branch management, automatic branch creation for shared workspaces, conflict detection, and AI-powered merge conflict resolution.
Provides management of tmux sessions for running Claude instances, including spawning new sessions, sending commands, reading output, and listing active sessions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tmux-claude MCP Server spawn two specialist instances for code review and testing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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.jsArchitecture
External State Store: JSON file-based registry for Phase 1, Redis-ready for Phase 2+
Project Isolation: Each Claude instance uses
--projectflag for conversation isolationRole-Based Access: Specialists have NO access to MCP tools, only Executive/Manager can orchestrate
Hierarchical Naming:
exec_1,mgr_1_1,spec_1_1_1for clear parent-child relationshipsNearly-Free Recovery: Restart instances using
--continueflag
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 operationsinstance.py ā
src/instance_manager.js- Instance lifecycle managementmanager.py ā
src/instance_manager.js- Registry and coordinationsession_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 installConfiguration (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.jsImportant notes:
The
-s userflag is REQUIRED for hierarchical orchestration to workThis 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.jsUsage
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:
Check if instance is actually dead
Recreate tmux session in same project directory
Launch
claude --project . --continueClaude 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 isolationGets 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 --helpSupported Time Formats
Relative:
+30m,+2h,+90m24-hour:
15:30,09:45,23:5912-hour:
3:30pm,9:45am,11:59PMNatural 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 suiteDevelopment
npm run dev # Start with file watchingArchitecture Documents
For complete implementation details, see:
docs/main/tmux-manager-MCP.md- MCP server specificationdocs/main/tmux-claude-implementation.md- Complete architecturedocs/main/tmux-mvp-implementation.md- Phase 1 MVP approachdocs/GIT_INTEGRATION_GUIDE.md- Git integration and workspace modesdocs/WORKSPACE_MODES.md- Detailed workspace mode documentationdocs/GIT_INTEGRATION_REFINEMENT_PLAN.md- Technical implementation details
Available Tools
14 toolscheck_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
Scored across 14 tools
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).
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.
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.
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
Related MCP Connectors
Shared long-term memory & Stop-hook task handoff across Claude Code, Codex, Cursor, and mobile.
AI routing, memory, guardrails, and governance. Routes across Claude, GPT, Gemini.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Related MCP Servers
- AlicenseAqualityDmaintenanceOrchestrates multiple Claude Code agents across iTerm2 sessions with process-level isolation, enabling collaborative AI development workflows on multiple codebases with task-based inter-agent communication and persistent state management.71MIT
- AlicenseAqualityCmaintenanceAn MCP server that gives orchestrator agents fine-grained control over interactive Claude Code sessions running inside tmux, enabling mid-session steering, interruption, and token-efficient result extraction.15MIT
- AlicenseNot gradedqualityDmaintenanceGives Claude Code terminal control and multi-agent coordination through tmux sessions.4MIT
- AlicenseAqualityAmaintenanceEnables Claude Code to launch and supervise multiple concurrent Claude Code sessions in tmux, sending them briefs, reading their progress, answering their prompts, and managing isolated git worktrees.202MIT