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 Claude
• workdir: 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 sessions

For 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)                    → cleanup

For 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:

1. Done indicator - Claude's status line showing ✻ model for Xm
2. 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>