smux CLI
A tuned tmux setup and the tmux-bridge CLI that lets agents read neighbouring panes, type into them and hand each other tasks.
- 1,532 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- An agent types text and keys into any tmux pane, including an open shell, which amounts to running commands as your user.
- The installer runs from the network through `curl | bash` and installs packages on the system.
Install
- Works in
Manual install
curl -fsSL https://shawnpana.com/smux/install.sh | bashThe first Install command from the README: installs tmux, the configuration, `tmux-bridge` and `smux-pane` into `~/.smux/`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- An agent types text and keys into any tmux pane, including an open shell, which amounts to running commands as your user.
- The installer runs from the network through `curl | bash` and installs packages on the system.
This is third-party code. Review the repository files before installing.
What it does
smux installs a tuned tmux and two CLIs in one command. Keys use Option with no prefix, the mouse selects and copies text, and panes carry labels. `tmux-bridge` reads the last lines of any pane, types into it and sends keys, so Claude Code can hand a task to Codex in the next pane and receive the answer in its own. The CLI insists on reading a pane before typing, so there is no need to poll another pane in a loop. The `smux` skill, installed with `npx skills add ShawnPana/smux`, teaches the agent that order and the raw tmux commands. The second CLI, `smux-pane`, remembers closed panes and windows and brings them back with their working directory and label. A pane that ran Claude Code returns with the same conversation.
Who it is for. People running several agents in neighbouring tmux panes who want them to exchange tasks and replies on their own.
Good fit when
- Claude Code asks Codex in the next pane to review the changes in `src/auth.ts`.
- An agent has to read the output of a long process in another pane and answer its confirmation prompt.
- A pane with a working Claude Code conversation was closed by accident and must come back with its session.
- You work in tmux and want one set of Option keys with no prefix, plus mouse selection.
Not a fit when
- The machine runs Windows: the installer targets macOS and Linux.
- Agents run in separate application windows rather than tmux panes.
- Neighbouring panes hold shells with live SSH connections where an agent must not type commands.
Example request
Label this pane claude, read the codex pane, ask it to review `src/auth.ts` and wait for the reply in your own pane.Limitations
macOS with Homebrew and Linux are supported. The installer fetches tmux 3.2 or newer and jq itself, and Windows is not among the requirements. Installation runs `curl ... | bash`, which executes a script from the network and installs packages through the system package manager, so read the script first. When a closed pane returns, only Claude Code is started again; other processes come back as a plain shell and scrollback is not kept. The last 25 closes are stored. By its metadata the skill requires `tmux` and `tmux-bridge` to be installed.
How to disable. `smux uninstall` removes the installation. Remove the skill with `npx skills remove smux`.
FAQ
How do I install smux for Claude Code?
Run `curl -fsSL https://shawnpana.com/smux/install.sh | bash`: it installs tmux, the configuration and both CLIs into `~/.smux/`. Then add the skill with `npx skills add ShawnPana/smux` so Claude Code learns about `tmux-bridge`.
How does one agent message another?
Through read, message, read, send: `tmux-bridge read codex 20`, then `tmux-bridge message codex 'text'`, another read and `tmux-bridge keys codex Enter`. The `message` command prepends the sender address, and the receiver replies to the pane named in that line.
Why does `tmux-bridge type` return an error?
The pane has not been read. Run `tmux-bridge read <label>` first and the write goes through. The mark is cleared after each successful write, so read the pane again before the next one.
How do I bring back a closed pane?
Press `Option+Shift+n` or run `smux-pane revive`. `smux-pane list` shows what can be reopened, and `smux-pane peek <pane>` previews the record without closing anything.
How do I update or remove smux?
Update with `smux update` and remove with `smux uninstall`. All files live in `~/.smux/`.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI and terminal app that show which coding agents in your tmux sessions are working, waiting on you or done
ccmux tracks every coding agent in tmux: who is working, who waits for you, worktree spawning and answer hand-off.
A tmux-based TUI that runs Claude Code, Codex and other agents in one list: status, quick prompts, worktrees and diff review
A Go terminal multiplexer with tiled panes that shows the state of Claude Code, Codex and other agents and gathers their requests in one list
botmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
A terminal workspace where several CLI agents like Codex, Claude and Gemini exchange messages and work on one task under human oversight
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| smux (this card) | no | 1,532 | ||
| Tmux MCP Server: agent access to tmux sessions | no | not required | 306 | gives an agent tmux tools through MCP; smux works with plain bash commands and adds a configuration, a skill and pane recovery |
| tmux-ide | yes | 563 | shows which agents in tmux sessions are working or waiting for a decision; smux passes messages between agents | |
| CCB (Claude Codex Bridge) | no | 3,609 | builds a separate workspace for several CLI agents; smux uses ordinary tmux panes |
README in short
The project has three parts: a tmux setup for the human, a CLI for agents and recovery of closed panes. Each part comes with a table of keys or commands.