claude-tmux-bridge

Claude Code MCP — tmux Bridge

An MCP server that connects Claude Desktop to an interactive Claude Code session running in a tmux terminal. Instead of spawning a one-shot process per prompt, it communicates with a persistent, visible session — so you can watch Claude work in real time while Desktop orchestrates the tasks.

How It Works

Claude Desktop  →  claude_code MCP tool  →  tmux session  →  Claude Code (interactive)
                        (this repo)

• Claude Desktop holds your project context, design decisions, and task history. It generates prompts and knows what needs to be done next.
• Claude Code runs interactively in a tmux terminal you can watch. It has access to all your configured MCP tools and retains full conversation history between calls.
• This server is the pipe between them — it delivers Desktop's prompts to Code's session and brings the response back.

Requirements

• macOS
• Node.js v20 or later
• tmux — brew install tmux
• Claude Code CLI — npm install -g @anthropic-ai/claude-code

Setup

1. Install this server

git clone https://github.com/DaRealDaHoodie/claude-tmux-bridge.git
cd claude-tmux-bridge
npm install
npm run build

2. Configure Claude Desktop

Add this server to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "claude-tmux-bridge": {
      "command": "node",
      "args": ["/path/to/claude-tmux-bridge/dist/server.js"]
    }
  }
}

Restart Claude Desktop after saving.

Using the Tool

Once configured, Claude Desktop has access to the claude_code tool. When sending a prompt tell Desktop:

• What to do — the task or question for Claude Code
• Which project — pass workFolder as the absolute path to your project directory

Example instruction to Desktop: > Use the claude_code tool with workFolder /Users/you/my-project and ask Claude Code to implement the feature we just designed.

Everything else is automatic — the tmux session and Claude Code instance are created on first use.

Session Naming

The tmux session name is derived from your project folder's basename:

| workFolder | Session name | |---|---| | /Users/you/my-project | claude-my-project | | /Users/you/other-project | claude-other-project | | (not provided) | claude-code |

Watching Claude Work

Sessions run in the background automatically. Attach any time to watch:

tmux attach -t claude-my-project
# Detach with Ctrl+B D

Tool Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | prompt | string | yes | The prompt to send to Claude Code | | workFolder | string | no | Absolute path to project — determines the session | | timeout | number | no | Max seconds to wait for a response (default: 300) |

Behaviour

• Session not found — auto-creates the tmux session rooted at workFolder
• Claude Code not running — auto-launches claude in the session and waits up to 30s for it to be ready
• Session busy — rejects with a "still busy" message; does not queue
• Timeout — auto-recovers on next call by checking if Claude has since finished
• Conversation history — fully preserved between calls (same interactive session)

Environment Variables

| Variable | Default | Description | |---|---|---| | MCP_CLAUDE_DEBUG | false | Set to true for verbose debug logging | | MCP_STARTUP_DELAY_MS | 1000 | Wait after sending prompt before polling starts | | MCP_POLL_INTERVAL_MS | 1500 | How often to poll the pane for output changes | | MCP_STABLE_THRESHOLD_MS | 3000 | Fallback: ms of no change before declaring done | | MCP_CLAUDE_READY_TIMEOUT | 30000 | Max ms to wait for Claude Code to start up |

Multiple Projects

Each project gets its own named tmux session. You can have multiple sessions open simultaneously — just pass the correct workFolder and Desktop will target the right one.

License

MIT