claude-mux.mcp

MCP server for tmux. Gives Claude Code terminal control and multi-agent coordination through tmux sessions.

Install

claude plugin add claude-mux@rtd

Then run /install inside Claude Code to verify dependencies and register the MCP server. It checks for bun and tmux, installs packages, and smoke-tests the server.

To update:

claude plugin update claude-mux@rtd

Then run /install again to verify everything is current.

Requirements

• tmux — brew install tmux on macOS, apt install tmux on Linux
• Bun — curl -fsSL https://bun.sh/install | bash

Manual install (development)

If you're working on the server itself, add to ~/.claude.json:

{
  "mcpServers": {
    "tmux": {
      "command": "bun",
      "args": ["/path/to/claude-mux.mcp/server.js"]
    }
  }
}

Actions

Observe

Action	What it does
list	All sessions. Named ones show windows; numbered ones get a one-line summary.
session	One session in detail, previewing each pane's last visible line.
read	Capture pane output. lines sets history depth (default 100).
tail	Last N lines, no pagination. Quick look at what just happened.
watch	Delta since last read. Only new lines come back.
transcript	Read a pane's prior Claude Code sessions from the on-disk JSONL — not scrollback. No name: lists the cwd's sessions newest-first with a title preview. With name (list index or session id): the flattened conversation, tool calls reduced to one-line breadcrumbs.
layout	Every pane across all sessions with dimensions and running process.
meta	Authoritative machine-parseable metadata for dashboards (no params). Tab-delimited rows, row-type letter in column 0 — one S row per session (named and numbered, no collapsing) and one W row per window. S\t<session_name>\t<session_activity>\t<session_attached>\t<session_created>; W\t<session_name>\t<window_index>\t<window_name>\t<window_activity>\t<window_active 0|1>. Epochs are raw seconds; session_attached is the raw client count (>0 = attached). TAB is the sole delimiter (window names may contain spaces and :).

Act

Action	What it does
type	Literal text, spaces preserved. No Enter appended.
typewait	Type literal text + Enter, then wait. One call for "run this and show me what happened."
keys	Space-separated key tokens: Escape :q! Enter, C-c, Down Down Enter.
keyswait	Send keys, poll until prompt appears or output settles. Returns the delta.
exec	Wrap a command in start/done markers, return a commandId. Non-blocking.
result	Check a tracked command's status, exit code, and output by commandId.

Manage

Action	What it does
new-session	Create a session.
kill-session	Kill a session.
new-window	Create a window in a session. Returns the target for subsequent calls.
kill-window	Kill a window.
split	Split a pane. Returns the new pane target. text: "horizontal" or "vertical" (default).
kill-pane	Kill a pane.
rename	Rename a window.

Coordinate

Cross-session agent messaging and task ownership. All state lives in tmux global environment and named buffers.

Action	What it does
register	Identify yourself by name. Stored globally so other agents can find you.
unregister	Remove your registration.
who	List all registered agents across all sessions.
post	Message an agent by name, or "all" for broadcast.
inbox	Check for new messages.
claim	Take a task. Atomic file lock prevents two agents from claiming the same one.
complete	Mark a task done, release the lock.
tasks	List all tasks with owner and status.

Workers

Spawn Claude Code instances as coordinating agents. Each worker gets a name, a team roster, and auto-injected inbox hooks so messages arrive without polling.

Action	What it does
spawn	One-shot claude -p. Auto-closes when done, captures output to a tmux buffer.
spawn-persist	Same, but the window stays open for inspection.
teammate	Interactive claude session. Stays alive for ongoing coordination.
despawn	Kill a worker, clean up registration and temp files.
worker-result	Read a completed worker's captured output.

Design notes

Plain text responses. list returns indented text, not nested JSON. Fewer tokens, easier for the model to parse.

Self-awareness. The server reads $TMUX_PANE on startup and reports you are here: main:0.1 in listings so the model knows which pane is itself.

type vs keys. keys splits on spaces — each token is a tmux key name. Good for Escape :q! Enter, destroys prose. type sends literal text with spaces intact.

exec/result for long commands. typewait blocks up to 30 seconds. exec drops start/done markers, returns a commandId immediately, and result checks on it later. Auto-detects zsh, bash, or fish.

Completion detection. keyswait and typewait poll every 500ms. Shell prompt means done. Output unchanged for 2s means settled. 30s timeout ceiling.

Atomic task claiming. claim uses O_EXCL file creation so two agents racing for the same task can't both win.

License

MIT