claude-tmux
MCP server for orchestrating multiple Claude Code instances via tmux.
Installation
Add to your Claude Code MCP settings:
{
"mcpServers": {
"claude-tmux": {
"command": "npx",
"args": ["-y", "claude-tmux"]
}
}
}Requirements
- tmux must be installed
- Claude Code CLI must be installed
Tools
spawn
Launch a new Claude Code instance in a tmux session.
spawn(name, prompt, workdir)name: Unique session name (e.g., 'refactor-auth', 'debug-api')prompt: Initial prompt to send to Claudeworkdir: Working directory for Claude to operate in
read
Wait for Claude sessions to finish working and return terminal output.
read(name: "task-name") // single session
read(names: ["a", "b", "c"]) // parallel wait on multiple sessionsFor multiple sessions, use names to wait in parallel - returns all outputs when all complete.
send
Send a follow-up message to a running Claude session.
send("task-name", "do something else")list
List all active Claude tmux sessions.
list()kill
Terminate a Claude tmux session and clean up resources.
kill("task-name")Usage Pattern
spawn(name, prompt, workdir) → start session
read(name) → wait for completion, get output
send(name, text) → steer with follow-up
read(name) → wait again
kill(name) → cleanupFor parallel tasks: `` spawn("task-a", ...) spawn("task-b", ...) spawn("task-c", ...) read(names: ["task-a", "task-b", "task-c"]) → wait for all ``
Idle Detection
read detects completion via:
- Done indicator - Claude's status line showing
✻ model for Xm - Stability - Output unchanged for 10 seconds (handles sub-minute tasks that don't show the indicator)
Timeout is 15 minutes.
Tips
- Verify output shows task completion before killing. Idle agents are fine to leave running.
- Attach manually:
tmux attach -t claude-<name>
