smux

One-command tmux setup with terminal automation for AI agents.

• For you — keyboard-driven tmux config with Option-key bindings, mouse support, and pane labels
• For agents — tmux-bridge CLI lets any agent read, type, and send keys to any pane
• Agent-to-agent — Claude Code can prompt Codex in the next pane, and Codex replies back. Any agent that can run bash can participate.

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

https://github.com/user-attachments/assets/9d5463ba-5972-4bbd-a07e-b585f1178011

Install

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

This installs:

• tmux if not already installed (via Homebrew, apt, dnf, pacman, or apk)
• tmux.conf with Option-key bindings, mouse support, pane labels, and a minimal status bar
• tmux-bridge CLI for cross-pane agent communication
• smux-pane CLI that lets closed panes and windows be reopened, like browser tabs
• jq if not already installed (used by smux-pane)

Everything lives in ~/.smux/.

Keybindings

All keybindings use Option (Alt) with no prefix required.

Panes

Windows

Scrolling

Mouse

• Click to select panes
• Drag to select text (auto-copies to clipboard)
• Scroll wheel to scroll

Reopening closed panes and windows

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. If the window is gone, it is recreated at its old number.
• Option+Shift+w closes a whole window as one entry, and reopening brings back all of its panes together.
• A pane that was running Claude Code resumes the exact conversation it had. 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.
• The last 25 closes are kept, newest first, and survive a tmux restart. Scrollback is not kept.

The keys call smux-pane, which you can also use directly:

Window numbers always match their position in the status bar: Option+m opens the new window right after the current one, and numbers close up when a window goes away.

tmux-bridge

A CLI for cross-pane communication. Any tool that can run bash can use it — Claude Code, Codex, Gemini CLI, or a plain shell script.

See the smux skill for full documentation on agent-to-agent workflows.

Update

smux update

Uninstall

smux uninstall

AI Agent Skills

Install the smux skill to teach your agents how to use tmux-bridge:

npx skills add ShawnPana/smux

Works with Claude Code, Codex, Cursor, Copilot, and 40+ other agents.

Requirements

• macOS (requires Homebrew) or Linux
• tmux 3.2+ (installed automatically)
• jq (installed automatically)

Sponsor

smux is free and maintained in my own time. Sponsoring keeps it that way.