tmux-bridge-mcp
Standalone MCP server for cross-pane AI agent communication via tmux. Lets Claude Code, Gemini CLI, Codex, and Kimi CLI talk to each other through tmux panes.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/howardpen9--tmux-bridge-mcp)HTML
<a href="/listings/howardpen9--tmux-bridge-mcp"><img src="/api/listings/howardpen9--tmux-bridge-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Prerequisites:** tmux 3.2+ and Node.js 18+ must be installed.
**One command to configure all your agents:**
npx tmux-bridge-mcp setup
This auto-detects Claude Code, Codex, OpenCode, CodeBuddy, Copilot CLI, Grok Build, Gemini CLI, and Kimi CLI on your machine, then writes the correct MCP config for each one. Done in seconds.
**Verify it works:**
npx tmux-bridge-mcp --help
You should see the version and available commands. Restart your AI agent to activate the new tools.
**See it in action:**
npx tmux-bridge-mcp demo
Opens a 3-pane tmux session and runs a live cross-pane communication demo.
<details> <summary>Manual setup (if you prefer)</summary>
**1. Install tmux**
brew install tmux # macOS apt install tmux # Linux
**2. Add to your agent's MCP config**
{
"mcpServers": {
"tmux-bridge": {
"command": "npx",
"args": ["-y", "tmux-bridge-mcp"]
}
}
}Restart your agent. It now has 9 MCP tools for cross-pane communication.
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 506 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # tmux-bridge-mcp
- **English** | [简体中文](README.zh-CN.md)
- 
- A standalone MCP server that lets AI agents (Claude Code, Gemini CLI, Codex, Kimi CLI) communicate with each other through tmux panes. It talks directly to tmux -- no external dependencies beyond tmux itself.
- ## 🖥️ What is tmux?
- [tmux](https://github.com/tmux/tmux) is a **terminal multiplexer** -- it lets you split one terminal window into multiple **panes**, each running its own process independently. Think of it as "tabs on steroids" for your terminal.
- 
- ```
- +-------------------------------+
- | Pane 1 | Pane 2 |
- | Claude Code | Codex |
- | writing code | reviewing |
- | | |
- +---------------+---------------+
- | Pane 3 | Pane 4 |
- | Gemini CLI | tail -f logs |
- | researching | monitoring |
- +-------------------------------+
- ```
- Each pane is a full terminal. You can have Claude Code running in one, Codex in another, Gemini in a third -- all visible at the same time, all on the same machine.
- **The problem:** these panes can't talk to each other. An agent in Pane 1 has no idea what's happening in Pane 2.
- 
- **tmux-bridge fixes this.** It gives every agent the ability to read, type, and send messages into any other pane.
- 
- ## ⚡ What can you do with tmux-bridge?
- Once installed, your AI agents can:
- | Action | How | Example |
- |--------|-----|---------|
- | **See what another agent is doing** | `tmux_read` | Read the last 20 lines of Codex's pane |
- | **Send a task to another agent** | `tmux_message` + `tmux_keys` | Tell Claude to review a file |
- | **Coordinate multi-agent workflows** | Chain tool calls | Gemini researches -> Claude implements -> Codex reviews |
- | **Monitor processes** | `tmux_read` on a shell pane | Watch build logs, test output, server status |
- | **Label panes by role** | `tmux_name` | Name panes "claude", "codex", "gemini" for easy targeting |
- All of this happens through standard MCP tool calls -- your agent doesn't need to learn any new syntax. If it supports MCP, it already knows how.
- ## 🤖 Supported Agents
- 
- ### Tested and documented
- | Agent | Connection | Setup path |
- |-------|------------|------------|
- | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Native MCP (stdio) | `claude mcp add -s user` / `~/.claude.json` |
- | [Codex CLI](https://github.com/openai/codex) | Native MCP (stdio) | `codex mcp add` |
- | [OpenCode](https://opencode.ai) | Native MCP (stdio) | `~/.config/opencode/opencode.json(c)` (`mcp` key) |
- | [CodeBuddy](https://www.codebuddy.ai) | Native MCP (stdio) | `codebuddy mcp add -s user` / `~/.codebuddy/.mcp.json` |
- | [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) | Native MCP (stdio) | `copilot mcp add` / `~/.copilot/mcp-config.json` |
- | [Grok Build](https://docs.x.ai/build/overview) | Native MCP (stdio) | `grok mcp add -s user` / `~/.grok/config.toml` |
- | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Native MCP (stdio) | `~/.gemini/settings.json` |
- | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) v1.26+ | Native MCP (`kimi mcp add`) | `kimi mcp add` |
- | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) older | Legacy wrapper (`kimi-tmux`) | wrapper binary |
- ### Should work (any MCP-compatible agent)
- | Agent | Notes |
- |-------|-------|
- | [Cursor](https://cursor.sh) | Supports MCP servers in settings |
- | [Windsurf (Codeium)](https://codeium.com/windsurf) | MCP server support |
- | [Aider](https://aider.chat) | Community MCP support |
- | [Continue.dev](https://continue.dev) | MCP server support |
- | [Cline](https://github.com/cline/cline) | VS Code extension with MCP |
- | [Roo Code](https://github.com/RooVetGit/Roo-Code) | Fork of Cline with MCP |
- | Any shell script or process | Read pane output with `tmux_read`, no MCP needed |
- tmux-bridge works with **any agent that supports MCP over stdio**. If your agent isn't listed, try adding the MCP config -- it will likely just work.
- ## 💡 Why
- When you run multiple AI agents in separate terminals, they work in isolation. You end up copy-pasting context between them, manually relaying questions and answers, or losing track of what each agent is doing.
- tmux-bridge solves this by giving every agent the ability to **read, type, and send messages into any other terminal pane** -- programmatically, through standard MCP tool calls.
- **Use cases:**
- - **Code review pipeline** -- Claude Code writes code in one pane, Codex reviews it in another, results flow back automatically
- - **Multi-model reasoning** -- ask Gemini for research, feed the findings to Claude, let Codex verify the implementation
- - **Parallel workflows** -- multiple Claude Code instances each handling a different part of a large task, coordinating through pane messages
- - **Monitoring** -- an agent reads log output from a `tail -f` pane and reacts to errors in real time
- **What you need:**
- | Requirement | Why |
- |-------------|-----|
- | **tmux** | The terminal multiplexer that hosts your panes -- this is the communication channel |
- | **Node.js 18+** | Runs the MCP server |
- | **At least one MCP-compatible agent** | Claude Code, Codex, OpenCode, CodeBuddy, Copilot CLI, Grok Build, Gemini CLI, or Kimi CLI v1.26+ |
- If you already use tmux to run multiple agents side by side, tmux-bridge just makes them aware of each other.
- ### 😩 Without tmux-bridge
- You're running Claude Code in one pane, Codex in another. Claude finishes writing a function and you want Codex to review it. Here's what actually happens:
- 1. You read Claude's output. Scroll up. Copy the relevant part.
- 2. Switch to Codex's pane. Paste it in. Type "review this code."
- 3. Codex gives feedback. You copy that.
- 4. Switch back to Claude. Paste Codex's feedback. "Fix these issues."
- 5. Repeat for every round of review.
- **You are the message bus.** Every interaction flows through your clipboard. You're not writing code anymore -- you're routing context between agents. With 3+ agents running, this becomes unmanageable within minutes.
- ### 🤔 Why not LangChain / CrewAI / A2A?
- | Approach | What it asks you to do | tmux-bridge difference |
- |----------|----------------------|----------------------|
- | **LangChain / CrewAI / AutoGen** | Rewrite your workflow inside their framework. Your agents must be Python objects in their orchestration layer. | You keep using Claude Code, Codex, Gemini CLI as-is. No framework, no SDK, no rewrite. |
- | **Google A2A Protocol** | Wait for agents to adopt a new protocol spec. Designed for distributed, networked agents. | Works today with any MCP agent. No protocol adoption needed. |
- | **Custom WebSocket / HTTP glue** | Build and maintain your own IPC layer. Handle serialization, discovery, error handling. | Zero infrastructure. tmux is the transport -- it's already running. |
- | **Shared files / pipes** | Roll your own convention. Each agent needs custom tooling to read/write. | Standard MCP tools. Any agent that speaks MCP gets cross-pane superpowers instantly. |
- **The key insight:** you don't need a multi-agent *framework*. You need your existing agents to *see each other*. tmux-bridge adds exactly that -- a thin MCP layer over tmux -- and nothing more.
- ## 🚀 Quick Start
- **Prerequisites:** tmux 3.2+ and Node.js 18+ must be installed.
- **One command to configure all your agents:**
- ```bash
- npx tmux-bridge-mcp setup
- ```
- This auto-detects Claude Code, Codex, OpenCode, CodeBuddy, Copilot CLI, Grok Build, Gemini CLI, and Kimi CLI on your machine, then writes the correct MCP config for each one. Done in seconds.
- **Verify it works:**
- ```bash
- npx tmux-bridge-mcp --help
- ```
- You should see the version and available commands. Restart your AI agent to activate the new tools.
- **See it in action:**
- ```bash
- npx tmux-bridge-mcp demo
- ```
- Opens a 3-pane tmux session and runs a live cross-pane communication demo.
- <details>
- <summary>Manual setup (if you prefer)</summary>
- **1. Install tmux**
- ```bash
- brew install tmux # macOS
- apt install tmux # Linux
- ```
- **2. Add to your agent's MCP config**
- ```json
- {
- "mcpServers": {
- "tmux-bridge": {
- "command": "npx",
- "args": ["-y", "tmux-bridge-mcp"]
- }
- }
- }
- ```
- Restart your agent. It now has 9 MCP tools for cross-pane communication.
- </details>
- ## 🔄 Updating
- ```bash
- # If installed globally
- npm update -g tmux-bridge-mcp
- # If using npx (auto-updates, but to force latest)
- npx tmux-bridge-mcp@latest
- # Check your current version
- npx tmux-bridge-mcp --version
- ```
- After updating, restart your agents to pick up the new version. If you use `npx` in your MCP config, it caches the package — run `npx --yes tmux-bridge-mcp@latest` once to pull the latest, then your agents will use it on next startup.
- ## 🏗️ How It Works
- 
- tmux-bridge runs as an MCP server over stdio. It calls tmux directly (`capture-pane`, `send-keys`, `list-panes`, etc.) -- no intermediate CLI layer.
- ```
- MCP path (Gemini, Claude Code, Codex, any MCP client):
- +--------------+ MCP/stdio +---------------+ tmux API +--------------+
- | MCP Agent |<----------->| tmux-bridge |<---------->| tmux panes |
- +--------------+ | MCP server | +--------------+
- +---------------+
- CLI path (Kimi):
- +--------------+ --print +---------------+ tmux API +--------------+
- | Kimi CLI |<----------->| kimi-tmux |<---------->| tmux panes |
- +--------------+ tool parse | adapter | +--------------+
- +---------------+
- ```
- 
- All cross-pane interactions follow the **read-act-read** workflow:
- 
- | Step | Action | Purpose |
- |------|--------|---------|
- | 1 | `tmux_read` | Read target pane (satisfies read guard) |
- | 2 | `tmux_message` / `tmux_type` | Type your message or command |
- | 3 | `tmux_read` | Verify text landed correctly |
- | 4 | `tmux_keys` | Press Enter to submit |
- | -- | STOP | Don't poll. The other agent replies directly into your pane. |
- The read guard is enforced at the MCP layer: `tmux_type`, `tmux_message`, and `tmux_keys` will fail unless you call `tmux_read` on the target pane first.
- ## ⚙️ Setup Per Agent
- ### Gemini CLI (native MCP)
- Add to `~/.gemini/settings.json`:
- ```json
- {
- "mcpServers": {
- "tmux-bridge": {
- "command": "npx",
- "args": ["tmux-bridge-mcp"]
- }
- }
- }
- ```
- ### Claude Code (native MCP)
- Add to your project's `.mcp.json` or global MCP config:
- ```json
- {
- "mcpServers": {
- "tmux-bridge": {
- "command": "npx",
- "args": ["tmux-bridge-mcp"]
- }
- }
- }
- ```
- ### Codex (native MCP)
- Add to your MCP config following the Codex MCP setup docs:
- ```json
- {
- "mcpServers": {
- "tmux-bridge": {
- "command": "npx",
- "args": ["tmux-bridge-mcp"]
- }
- }
- }
- ```
- ### OpenCode
- `opencode mcp add` is interactive. `tmux-bridge-mcp setup` writes directly to
- `~/.config/opencode/opencode.json` (or `.jsonc`):
- ```json
- {
- "mcp": {
- "tmux-bridge": {
- "type": "local",
- "command": ["npx", "-y", "tmux-bridge-mcp"],
- "enabled": true
- }
- }
- }
- ```
- ### CodeBuddy (Tencent)
- ```bash
- codebuddy mcp add -s user tmux-bridge -- npx -y tmux-bridge-mcp
- ```
- Fallback config path: `~/.codebuddy/.mcp.json` (standard `mcpServers` JSON).
- ### GitHub Copilot CLI
- ```bash
- copilot mcp add tmux-bridge -- npx -y tmux-bridge-mcp
- ```
- Fallback config path: `~/.copilot/mcp-config.json`:
- ```json
- {
- "mcpServers": {
- "tmux-bridge": {
- "type": "local",
- "command": "npx",
- "args": ["-y", "tmux-bridge-mcp"],
- "tools": ["*"]
- }
- }
- }
- ```
- ### Grok Build
- ```bash
- grok mcp add -s user tmux-bridge -- npx -y tmux-bridge-mcp
- ```
- Fallback TOML in `~/.grok/config.toml`:
- ```toml
- [mcp_servers.tmux-bridge]
- command = "npx"
- args = [
- "-y",
- "tmux-bridge-mcp",
- ]
- enabled = true
- ```
- ### Kimi CLI
- ```bash
- # Check your Kimi version
- kimi --version
- # v1.26+ → use native MCP (recommended)
- # older → use kimi-tmux wrapper
- ```
- **Native MCP (recommended, v1.26+):**
- ```bash
- kimi mcp add tmux-bridge -- npx tmux-bridge-mcp
- ```
- Once added, Kimi uses all tmux-bridge tools directly -- no adapter needed.
- **Legacy wrapper (older versions):**
- For Kimi CLI versions without native MCP, `kimi-tmux` bridges the gap by injecting the system instruction as a prompt, running Kimi in `--print` mode, parsing tool-call blocks from output, and executing them via tmux.
- ```bash
- kimi-tmux "list all tmux panes"
- kimi-tmux "ask the agent in codex pane to review src/auth.ts"
- kimi-tmux "read what claude is working on"
- kimi-tmux --rounds 3 "send a message to gemini and wait for the result"
- ```
- 
- ## 🔧 Tools Reference
- | Tool | Description |
- |------|-------------|
- | `tmux_list` | List all panes with target ID, process, label, and working directory |
- | `tmux_read` | Read last N lines from a pane (satisfies read guard) |
- | `tmux_type` | Type text into a pane without pressing Enter (requires prior read) |
- | `tmux_message` | Send message with auto-prepended sender info (requires prior read) |
- | `tmux_keys` | Send special keys -- Enter, Escape, C-c, etc. (requires prior read) |
- | `tmux_name` | Label a pane for easy targeting (e.g., "claude", "gemini") |
- | `tmux_resolve` | Look up pane ID by label |
- | `tmux_id` | Print current pane's tmux ID |
- | `tmux_doctor` | Diagnose tmux connectivity issues |
- Targets can be a pane ID (`%0`), session:window.pane (`main:0.1`), or a label (`claude`).
- ## 📖 Examples
- ### Ask Claude to review a file (from Gemini)
- ```
- tmux_list()
- tmux_read(target="claude", lines=20)
- tmux_message(target="claude", text="Please review src/auth.ts for security issues")
- tmux_read(target="claude", lines=5)
- tmux_keys(target="claude", keys=["Enter"])
- ```
- ### Multi-agent coordination (from Kimi)
- ```bash
- kimi-tmux "tell the claude pane to run the test suite"
- kimi-tmux "ask gemini to summarize the test results in claude's pane"
- ```
- ### Multi-agent layout
- ```
- +-----------------------------------------------------------+
- | tmux session |
- | |
- | +------------+ +------------+ +----------+ +-----------+ |
- | | Claude Code | | Codex | | Gemini | | Kimi | |
- | | (MCP) | | (MCP) | | (MCP) | |(kimi-tmux)| |
- | | | | | | | | | |
- | | label: | | label: | | label: | | label: | |
- | | claude | | codex | | gemini | | kimi | |
- | +-----+------+ +-----+------+ +----+-----+ +-----+-----+ |
- | +---------------+-----------+--------------+ |
- | tmux-bridge (direct tmux IPC, no deps) |
- +-----------------------------------------------------------+
- ```
- ## 🌐 Environment Variables
- | Variable | Description | Default |
- |----------|-------------|---------|
- | `TMUX_BRIDGE_SOCKET` | Override tmux server socket path | Auto-detected from `$TMUX` |
- | `KIMI_PATH` | Path to `kimi` binary (kimi-tmux only) | `kimi` (in PATH) |
- ## 🔒 Security Model
- tmux-bridge is designed for **local development on a single machine**. It assumes all connected MCP agents are trusted:
- - Any agent can read from or write to **any pane** in the tmux server — there is no per-pane access control.
- - The **read guard** (must `tmux_read` before `tmux_type`/`tmux_keys`) is a sequencing aid to prevent blind typing. It is **not a security boundary**.
- - Pane labels set via `tmux_name` are **not authenticated** — any agent can label or relabel any pane.
- - There is no encryption or authentication between agents. Communication happens through tmux's own IPC (Unix socket).
- **Do not use tmux-bridge in multi-tenant environments** or expose the tmux socket over a network. It is built for the common case: one developer running multiple AI agents side by side on their own machine.
- ## 📝 System Instruction
- For agents that support custom system prompts, use `system-instruction/smux-skill.md`. It teaches the read-act-read workflow and documents all available MCP tools.
- ## 🔗 Related Projects
- | Project | Approach | Focus |
- |---------|----------|-------|
- | [smux](https://github.com/ShawnPana/smux) | tmux skill + bash CLI | Agent-agnostic tmux setup |
- | [agent-bridge](https://github.com/raysonmeng/agent-bridge) | WebSocket daemon + MCP plugin | Claude Code <-> Codex |
- | **tmux-bridge-mcp** (this) | Standalone MCP server + direct tmux | Any agent, zero deps beyond tmux |
- ### smux vs tmux-bridge-mcp
- | Dimension | smux | tmux-bridge-mcp (this) |
- |-----------|------|------------------------|
- | 🔌 **How agents connect** | Agent runs bash commands (`tmux-bridge read/type/keys`) | Agent uses MCP tool calls (`tmux_read/tmux_type/tmux_keys`) |
- | 🚀 **Agent onboarding** | Install skill or inject system prompt to teach bash commands | Add MCP config JSON -- agent auto-discovers 9 tools |
- | 📦 **Prerequisites** | `curl \| bash` installs tmux + tmux.conf + CLI script | Just tmux + Node.js, `npx` to run |
- | ⚙️ **tmux configuration** | Ships full tmux.conf (keybindings, mouse, status bar) | Doesn't touch tmux.conf -- no config conflicts |
- | 🛡️ **Read guard** | Bash CLI layer (`/tmp` file lock) | MCP server layer (`/tmp` file lock, same concept) |
- | 💻 **Language** | Bash (~300 LOC) | TypeScript (~600 LOC) |
- | 📥 **Install** | `curl \| bash`, writes to `~/.smux/` | `npm install -g` or `npx` |
- | 🤝 **Agent compatibility** | Any agent that can run bash (needs skill/prompt) | Any agent with MCP support (standard protocol) |
- 👉 **When to use smux:** You want a complete tmux setup (keybindings, mouse support, status bar) and your agents support the skills system or you're comfortable injecting system prompts.
- 👉 **When to use tmux-bridge-mcp:** You want a drop-in MCP server that works with any MCP-compatible agent out of the box, without touching your tmux configuration.
- ### tmux-bridge (`/tmb`) vs Claude Code Native (subagent + `/codex` + `/gemini`)
- | Dimension | tmux-bridge | Claude Code Native |
- |-----------|-------------|-------------------|
- | **Context isolation** | Each pane has its own full conversation context, persists across interactions | subagent spawns fresh each time, gone when it finishes |
- | **Persistence** | Pane stays alive, accumulates conversation history | Fire-and-forget, must re-provide context next time |
- | **Parallelism** | Truly independent processes, no interference | Agent tool can parallelize, but shares billing/rate limits |
- | **Model diversity** | Each pane can run a different CLI (Codex, Gemini, Kimi) | `/codex` `/gemini` can do this too -- not a real differentiator |
- | **Communication overhead** | Goes through tmux read/send, has latency, messages may get truncated | Native tool calls, structured returns, high reliability |
- | **Result integration** | You must read pane output, parse, and synthesize manually | subagent returns structured results directly, ready to use |
- | **Operational complexity** | Extra layer of tmux management (labels, pane IDs) | One tool call, done |
- | **Cost** | Each pane consumes its own token budget independently | subagent shares the same session's token pool |
- **Verdict**
- tmux-bridge's real advantage comes down to one thing: **persistent context**. If you need an agent that remembers the last 30 turns of conversation and keeps following up on the same task, a tmux pane can do that -- a subagent cannot.
- But for most tasks, native is better:
- - Communication is more reliable (no tmux buffer truncation)
- - Results are structured -- no need to parse terminal output
- - Simpler to operate, one less layer of abstraction
- **Practical guidance:**
- - **Short-lived, one-off tasks** → native subagent / `/codex` / `/gemini`
- - **Long-running sessions that need accumulated context** (e.g., a reviewer continuously following the same PR) → tmux-bridge adds real value
- - A multi-pane multi-role layout only pays off if each role genuinely needs cross-conversation state -- otherwise the overhead outweighs the benefit
- ## 📄 License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.