mirror of https://github.com/ShawnPana/smux.git synced 2026-09-14 16:04:27 +08:00

Files

T

Shawn Pana cd26d2d87b Option+Escape leaves fullscreen; re-tile the origin window on join

Teach toggle-fullscreen a second mode, 'exit', that only performs the
un-fullscreen branch and never breaks a pane out. Bind Option+Escape
(M-Escape) to that mode so the key is a pure "leave fullscreen if
you're in one" — no-op on a pane that isn't currently fullscreened, no
risk of surprising the user into fullscreen. Both keys also now call
smart-layout on the pane's newly-joined window after join-pane, so
returning a pane to a two-pane layout reshapes into whichever tiling
best fits the window shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 14:01:58 -07:00

3.1 KiB

Raw Permalink Blame History

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

Everything lives in ~/.smux/.

Keybindings

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

Panes

Key	Action
`Option+i/k/j/l`	Navigate up/down/left/right (no wrap)
`Option+n`	New pane (split + auto-tile)
`Option+w`	Close pane
`Option+o`	Re-tile panes into the best-fit layout for the window shape
`Option+p`	Cycle through tmux's built-in layouts
`Option+g`	Mark pane
`Option+y`	Swap with marked pane
`Option+f`	Toggle pane fullscreen (move to own window, toggle back)
`Option+Escape`	Leave fullscreen (no-op if the pane isn't fullscreened)

Windows

Key	Action
`Option+m`	New window
`Option+u`	Next window
`Option+h`	Previous window

Scrolling

Key	Action
`Option+Tab`	Toggle scroll mode
`i/k`	Scroll up/down
`Shift+I/K`	Half-page up/down
`q` or `Escape`	Exit scroll mode

Mouse

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

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.

Command	Description
`tmux-bridge list`	Show all panes with target, process, label
`tmux-bridge read <target> [lines]`	Read last N lines from a pane
`tmux-bridge type <target> <text>`	Type text into a pane (no Enter)
`tmux-bridge keys <target> <key>...`	Send keys (Enter, Escape, C-c, etc.)
`tmux-bridge name <target> <label>`	Label a pane for easy addressing
`tmux-bridge resolve <label>`	Look up a pane by label
`tmux-bridge id`	Print this pane's ID

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)

3.1 KiB Raw Permalink Blame History