tmux

A second terminal driver beside skills/cmux. It speaks the workplace JSON protocol (docs/workplace.md § Writing a driver), so the plan, the briefing, the inbox and the cockpit work the same in any terminal app that runs tmux.

Optional. It needs the tmux binary ($BRIDGE_TMUX_BIN, else tmux on PATH, else Homebrew's path). Without it the driver answers an error, which scripts/workplace.py reads as "tab view unknown", never as "no tabs open".

Wire it

workplace:
  driver: {command: ["python3", "${root}/skills/tmux/scripts/tmux_driver.py"]}

Then python3 scripts/workplace.py open --yes [--here "$TMUX_PANE"], launch, status, send and adopt steer the tabs, exactly as with cmux. BRIDGE_TMUX_SOCKET=<name> points the driver at a separate server (tmux -L <name>); the tests use that so they never touch your own tmux.

Mapping

All these verbs are served: tabs, sessions, open, launch, send, rename, control, caps, focus, key, keys, screen, close, rename_workspace, move_tab, new_tab, new_workspace, close_workspace. rename_workspace renames the session by its id, with : and . turned into _ as tmux does, and refuses a name another session has after that same change. move_tab moves a window into another session (move-window -d, without an index) and never the last window of a session. new_tab adds a window to a session by its id and new_workspace makes a session (neither is selected), both answering the new refs; new_workspace refuses a name in use and a colour. close_workspace kills one session and never the last one of the server. tmux has no workspace colour or description, so set_color and set_description are not offered.

What it guarantees

• It never closes a window or a session on its own. close kills one pane on request, and refuses the last pane of the server, which would end the server; close_workspace kills one session on request and refuses the last session.
• It never moves the last window out of a session (tmux destroys an emptied session); such a tab is renamed where it is and the report says so.
• open and control reuse a window of the same name in the target session. launch does not, like cmux: workplace.py already skips an agent that runs, and --again asks for a second tab on purpose.
• launch --target tab opens in the caller's session (here, else $TMUX_PANE) and refuses when neither is known, never the attached session.
• A command over 1000 bytes goes into a private launcher file (~/.cache/bridge-tmux/commands/, mode 0600, pruned after 7 days), since tmux carries a command in one message of at most 16 KB. Every command keeps a shell open after the agent exits.
• A step tmux refuses is an ERROR line, never a success line. No server running is a true "no tabs".

Limits, honestly

• State is read from the screen, not reported by the agent: cmux gets it from Claude Code's hooks. A new agent UI wording can misread a state until the patterns in tmux_driver.py follow it.
• No colors, descriptions or ordering for workspaces: tmux has no sidebar. The plan's order and colors are not applied.
• No notifications. cmux can flag a tab that needs you; in tmux the cockpit has to poll tabs.
• focus needs an attached client. Without one the window is selected and shows on the next tmux attach; with several clients only the first switches.
• A workspace created only to receive moved tabs keeps its starting shell window, since tmux cannot create a session around an existing window.
• Untested with agents other than Claude Code and Codex.