smux gives tmux Option key bindings and a bridge that lets agents talk to each other

A tmux config, and two CLIs on top of it

smux is a tmux config with built-in terminal automation and agent-to-agent communication, and the subtitle says it plainly. One-command tmux setup with terminal automation for AI agents.

There are two audiences in the readme, and they are stated as separate bullets. For you, it is a keyboard-driven tmux config with Option key bindings, mouse support and pane labels. For agents, the tmux-bridge CLI lets any agent read, type and send keys to any pane.

That split is the design. Most tmux configurations start from the assumption that the person is the only actor, so every binding is a shortcut for a human hand. This one adds a machine interface to the same multiplexer, and the same pane can be driven by a person with the Option key or by an agent with a command line.

The implementation language is Shell, the licence is MIT, and the last push was on 2026-10-05. The repository has no GitHub releases, and the top level listing is small, with a .tmux.conf file, an install.sh, a scripts/ directory, a skills/ directory for the agent skill, a ghostty/ directory and the README.

The framing in the third bullet is the one that makes this more than a dotfiles repository. Claude Code can prompt Codex in the next pane, and Codex replies back, and any agent that can run bash can participate.

One install command, five things installed

The installation is a single command that pipes a script into a shell.

curl -fsSL https://shawnpana.com/smux/install.sh | bash

The readme then lists what that installs, and the list is worth reading because it is wider than a tmux configuration.

First, tmux itself, if it is not already installed, through Homebrew, apt, dnf, pacman or apk depending on the platform. Then tmux.conf, with the Option key bindings, mouse support, pane labels and a minimal status bar. Then the tmux-bridge CLI for cross-pane agent communication. Then smux-pane, a CLI that lets closed panes and windows be reopened like browser tabs. And finally jq, if it is not already installed, which smux-pane uses.

Everything lives in ~/.smux/, so the installation is self contained and the configuration is easy to remove or to copy to another machine.

The install script is in the repository rather than only on the website, so you can read it before running it, which is the right habit with a curl-to-bash installer. The requirements section puts the floor on tmux at 3.2, and the platform list is macOS, which requires Homebrew, or Linux.

Option key bindings, with no prefix at all

All keybindings use Option, also known as Alt, with no prefix required, and the tables are organised by what they act on.

For panes, Option with i, k, j and l navigates up, down, left and right without wrapping, and adding Shift swaps the pane with its neighbour in the same direction. Option+n opens a new pane with a split and an automatic tile, Option+w closes a pane, Option+Shift+w closes a window, and Option+Shift+n reopens the last closed pane or window. Option+o cycles the layouts, Option+g marks a pane and Option+y swaps with the marked one.

For windows, Option+m opens a new window placed right after the current one, Option+u and Option+h move to the next and previous window, and adding Shift moves the window itself right or left.

Scrolling has its own mode. Option+Tab toggles scroll mode, i and k scroll up and down, Shift with I and K moves half a page, and q or Escape leaves the mode.

The mouse support is three lines and each is the behaviour people expect from a modern terminal. Click to select panes, drag to select text with an automatic copy to the clipboard, and the scroll wheel to scroll.

What makes the no-prefix choice work is the Option key rather than a leader. There is no chord to press before a command, so every binding is a single keystroke, which is a different feel from the usual Ctrl-b prefix and is the main thing a person notices on the first day.

Closed panes come back, and a Claude Code session resumes

The reopen feature is the most unusual part of the configuration, and it is explained in terms of browser tabs.

Closing works like closing a browser tab: the process really ends, but enough is remembered to bring the pane back with Option+Shift+n. A pane returns to the slot it had in its window, with its label and working directory, and if the window is gone it is recreated at its old number.

The detail that makes it interesting is about agents. A pane that was running Claude Code resumes the exact conversation it had, because the session is read from the file Claude Code keeps for each running process, so it survives moving the pane around. Other processes are not restarted, you get a shell where they were.

So the pane store is not a terminal multiplexer feature, it is a way of suspending an agent conversation and picking it back up. That is a capability you cannot get from tmux alone, and it is the kind of thing that changes how you work when you keep several agents going at once.

The bookkeeping has limits that the readme states. The last 25 closes are kept, newest first, and they survive a tmux restart. Scrollback is not kept.

The commands are exposed directly through smux-pane as well as through the key binding, and one of them is worth knowing about. The peek command shows what closing a pane would record, without closing it, which is the dry run for an operation whose default is to kill a process.

tmux-bridge turns a pane into something an agent can drive

tmux-bridge is a CLI for cross-pane communication, and the readme is blunt about who can use it. Any tool that can run bash can use it, naming Claude Code, Codex, Gemini CLI, or a plain shell script.

The command set is small.

tmux-bridge read codex 20          # read the pane
tmux-bridge type codex "review src/auth.ts"  # type into it
tmux-bridge keys codex Enter       # press enter

The full table has seven entries. list shows all panes with their target, process and label. read takes a target and an optional number of lines and reads the last N lines from a pane. type takes a target and text and types it without pressing Enter. keys sends keys such as Enter, Escape or C-c. name labels a pane so it can be addressed by a name rather than a number. resolve looks up a pane by its label. And id prints the identifier of the current pane, which is what an agent needs to refer to itself.

The separation between type and keys is the detail that matters. Type does not submit, and keys submits. An agent that wants to write a prompt into a pane and then let the other agent think reads the pane, types a question, sends Enter, and reads again, which is a workable conversation protocol built out of three commands.

The skill is how an agent learns the protocol

The repository has a skills/ directory and an agent skill that teaches the tools to use tmux-bridge, and the readme says the skill documents the agent-to-agent workflows in full.

It is installed with the skills tooling.

npx skills add ShawnPana/smux

And the readme claims it works with Claude Code, Codex, Cursor, Copilot, and 40 or more other agents.

That claim is the interesting one, because it depends on a convention rather than on an integration. A skill is a document that is loaded into an agent's context, so any agent that supports the convention can read the same instructions. There is no plugin to install per agent, which is why the list of supported agents is as long as it is.

The practical benefit is that the agent does not have to guess the tmux-bridge commands or work out the conversation protocol from the readme. The readme is written for a person, and a person already knows what a pane is. An agent does not, and the skill is what bridges that gap.

The agent-to-agent flow the readme describes is the same one the commands support. One agent prompts another in the next pane, the other replies, and the first reads the reply. That is a plain request and response over a terminal, with the multiplexer providing the addressing.

Updates, removal, and who pays for it

The maintenance commands are two, and they are the same shape as the install.

smux update

smux uninstall

The requirements are the short list again. macOS, which requires Homebrew, or Linux, tmux 3.2 or newer which is installed automatically, and jq, also installed automatically.

The last section is the sponsor note, and it is worth quoting in full because it tells you what kind of project this is. smux is free and maintained in my own time, and sponsoring keeps it that way.

So there is no company behind this, and the maintenance model is a person and a sponsorship link. For a configuration that people install with curl and then live in every day, that is a real consideration, and it is also why the project is small and opinionated rather than a general terminal setup with a plugin system.

There is also a ghostty/ directory in the repository, which suggests the configuration is tested against that terminal emulator, and the scripts/ directory holds the install and update logic. The whole project fits in a handful of files, which is the point of a configuration you are expected to read rather than configure.

Editorial conclusion

Adopt smux if you live in tmux and want the Option key bindings and the reopenable panes, and you are also running coding agents that need to drive each other's terminals. Do not adopt it if you need Windows support, since the requirements are macOS with Homebrew or Linux, and read the tmux-bridge section carefully first, because giving an agent the ability to type into any pane is a real permission decision rather than a convenience.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. ShawnPana/smux on GitHub