tmux-claude

tmux-claude is an MCP server that orchestrates Claude instances through a bridge pattern using tmux. It exposes core MCP tools such as spawn, send, read, list, and terminate to manage hierarchical Claude actors (Executive, Manager, Specialist) within tmux sessions. The server emphasizes memory efficiency by centralizing state and routing commands through a single bridge, enabling multi-instance coordination without spawning multiple full MCP processes. Users can leverage the provided tooling to create new Claude instances, prompt them with messages, retrieve their outputs, monitor active sessions, and gracefully terminate sessions as needed. The web-based monitoring dashboard included with the project offers real-time visibility into active instances and system metrics, aiding observability and debugging.

Prerequisites:

• Node.js v18.0.0 or newer
• npm (comes with Node.js)
• Git (optional, for cloning the repository)

Installation steps:

1. Install Node.js (v18+)

   • On macOS/Linux: install from nodejs.org or use nvm
   • On Windows: install from nodejs.org

2. Install the MCP server package (from GitHub repository)

   • Clone the repo: git clone https://github.com/michael-abdo/tmux-claude-mcp-server.git
   • Navigate to the project directory: cd tmux-claude-mcp-server
   • Install dependencies: npm install

3. Configure environment (optional but recommended)

   • Create a .env file or rely on the env block in mcp_config to set PORT, TMUX_CMD, LOG_LEVEL, etc.

4. Run the MCP server (see mcp_config for details)

   • If you use the npm script (if defined): npm run start
   • Or run directly: node src/simple_mcp_server.js

5. Verify operation

   • Check logs for startup messages
   • Use MCP tooling to spawn and manage Claude instances via the bridge

Tips and common considerations:

• The server uses a bridge pattern to share a single MCP process while allowing multiple Claude instances to be controlled via tmux sessions. This reduces memory usage and avoids race conditions.
• The core tools (spawn, send, read, list, terminate) should be used through your MCP client interface to manage instance lifecycles and messaging.
• If you enable the web dashboard, ensure your environment allows the required port to be accessible for monitoring.
• For production, consider configuring proper logging levels, persistent storage for session state, and securing access to the MCP endpoints.
• If you encounter issues with tmux path resolution, verify TMUX_CMD points to the correct executable in your environment.
• The project emphasizes hierarchical naming (exec_1, mgr_1_1, spec_1_1_1); adhere to this when initiating or querying instances to keep orchestration predictable.