tmux-mcp

Agent-oriented MCP server for tmux and herdr — native process detection, smart triggers, and one handle: the slot.

Quick start

Prerequisites: tmux or herdr installed, Go 1.26.1+ or a pre-built binary.

# Install via Go
go install github.com/MadAppGang/tmux-mcp/v2@latest

# Or build from source
git clone https://github.com/MadAppGang/tmux-mcp
cd tmux-mcp && go build -o tmux-mcp .

Add to your MCP client config (~/.claude/settings.json for Claude Code):

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp",
      "args": ["--shell-type", "zsh"]
    }
  }
}

Get a terminal and run something in it — no setup call, no handle to carry:

// A pane beside the agent is created on first use. Synchronous: blocks until
// the command finishes, and returns output plus the exit code.
{"tool": "execute-command", "params": {"command": "go build ./..."}}
// → {"slot": 1, "created": true, "output": "", "exitCode": 0, "timedOut": false}

// The same slot is the same pane next time.
{"tool": "capture-pane", "params": {}}
// → the pane's text, with structuredContent {"slot": 1}

Why this exists

AI coding…