Skip to main content
Glama
PiMPStudios

claude-tmux-bridge

by PiMPStudios
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

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.

Related MCP server: codex-cli-mcp-tool

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

Available Tools

1 tool
claude_codeA

Send a prompt to an interactive Claude Code session running in a tmux terminal.

Sessions and Claude Code are started automatically if not already running. The user can attach to the session at any time to watch Claude work: tmux attach -t {session-name}

SESSION NAMING: workFolder /Users/you/my-roblox-game → session: claude-my-roblox-game No workFolder → session: claude-code

BEHAVIOUR: • If the tmux session doesn't exist it is created automatically. • If Claude Code isn't running in the session it is started automatically. • Only one prompt at a time per session — concurrent calls return a busy error. • Conversation history is fully preserved between calls. • Claude Code has access to all configured MCP tools (Roblox Studio, Godot, Blender, etc.).

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe prompt to send to the Claude Code session.
compactNoSend /compact to the Claude Code session before delivering the prompt. Summarises conversation history via the Claude API, keeping key context while freeing up space. Use when context is growing but continuity still matters. Slower than clearContext (30–60s). If both are set, compact takes precedence.
timeoutNoMax seconds to wait for a response (default: 300).
workFolderNoAbsolute path to the project folder. Determines the tmux session name and sets the working directory when creating a new session. E.g. /Users/foo/my-project → session "claude-my-project".
clearContextNoSend /clear to the Claude Code session before delivering the prompt. Wipes conversation history entirely — use when starting a new major feature, a new work session, or when Claude Code warns about large context. Fast (< 1s).

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It excels: auto-start behavior, busy error on concurrent calls, full conversation history preservation, MCP tool access, and session naming rules are all clearly disclosed. This gives the agent a robust understanding of side effects and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections (SESSION NAMING, BEHAVIOUR) and bullet points. Each sentence carries useful information without redundancy. It is appropriately sized for the tool's complexity, front-loading the core purpose, and every line earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers a wide range of context: session naming, auto-start, concurrency, history, and MCP access. However, it does not specify the return value shape (e.g., whether it returns the full Claude response or just a status), which would be valuable given the absence of an output schema. This is a minor gap in an otherwise thorough description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema itself already documents all parameters in detail, including use cases for compact and clearContext. The main description adds only session naming context, which is also present in the workFolder parameter description. The description provides no significant semantic value beyond what the schema offers, matching the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource statement: 'Send a prompt to an interactive Claude Code session running in a tmux terminal.' It clearly identifies the tool's function and scope. Even without siblings to distinguish from, the purpose is unambiguous and detailed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when the tool should be used, including automatic session creation and the concurrency limitation. It doesn't explicitly name alternatives (no sibling tools exist), but parameter descriptions for compact and clearContext offer strong usage guidance for choosing between them, effectively covering the when/when-not aspect.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The single tool's purpose is crystal clear.

Naming Consistency5/5

With only one tool, naming consistency is trivially maintained. The name 'claude_code' accurately reflects its function.

Tool Count3/5

One tool feels thin for a bridge server, but it does encapsulate the core operation. A more complete set might include session management tools.

Completeness4/5

The tool covers the primary use case of sending prompts and implicitly handles session startup. Minor gaps like explicit session listing or termination exist.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • cc-tap

    es617
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that bridges Claude Desktop and Claude Code by letting Desktop read and interact with Claude Code Remote Control sessions, enabling cross-agent coordination.
    6
    3
    MIT

  • claude-code-mcp

    joschi655
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that gives orchestrator agents fine-grained control over interactive Claude Code sessions running inside tmux, enabling mid-session steering, interruption, and token-efficient result extraction.
    15
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PiMPStudios/claude-tmux-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server