Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling

What it claims

The guide is a practical tmux recipe for running Claude Code and other coding agents. It argues that tmux suits agents for three reasons: the server owns the pty, so agents survive closed windows and dropped SSH; many sessions fit in one window; and any shell can type into or read from a running agent. It also lists the specific ways tmux falls short once several agents need attention. The final section is vendor promotion for crystl, a macOS terminal, and the guide's recommendation is to keep tmux for remote boxes and SSH.

How to use it

The built-in path is claude --worktree --tmux, with an optional worktree name such as claude --worktree auth-refactor --tmux. Two details matter. --tmux errors without --worktree. On iTerm2 it uses native panes rather than tmux, so nothing exists for tmux commands to attach to. Pass --tmux=classic to get real tmux, which is needed for any scripting. The flag does not run several agents in one session, script input, report waiting agents, or set anything up over SSH.

For the manual setup, the guide uses one session per repo, created with attach-or-create:

tmux new-session -A -s api -c ~/code/api

Session names cannot contain . or :, because tmux uses them as target separators. New panes need -c '#{pane_current_path}', otherwise the agent starts in the session's original directory. main-pane-width 60% requires tmux 3.2 or newer.

The .tmux.conf changes specific to agents are:

• history-limit 100000
• allow-rename off and automatic-rename off, because agent TUIs rename windows
• escape-time 10, which fixes laggy arrow keys inside agent TUIs
• monitor-activity on
• status-interval 5

The reliable send-keys pattern sends literal text, waits, then sends Enter:

tmux send-keys -t api:auth -l "$PROMPT"
sleep 0.3
tmux send-keys -t api:auth Enter

Without -l, standalone words such as Enter, Escape or Space are sent as keypresses. A ; in the text ends the tmux command unless it is escaped as \;. Many agent input boxes swallow an Enter that arrives in the same frame as the pasted text.

For reading output, tmux capture-pane -p -J -S -200 -t api:auth captures the last 200 lines. The -J flag rejoins wrapped lines; without it, grep fails at the line seams. pipe-pane -o streams a pane to a file, and running it a second time turns it off. Its output contains raw ANSI escape sequences.

The status-line monitor runs a script through #() every 5 seconds. The script runs capture-pane on the last 8 lines of each pane and matches strings. "Do you want" or "❯ 1." means the agent is waiting on a prompt, and "esc to interrupt" means it is working. The native alternative is monitor-silence 30 with an alert-silence hook.

Over SSH, ssh devbox -t tmux new-session -A -s agents reconnects to the same session after a drop. The guide suggests mosh for bad links. For nested tmux, it suggests a different prefix on the remote host or bind C-b send-prefix.

Limits

The guide states these limits:

• The status-script match strings depend on the current Claude Code UI and break when it changes.
• Silence is not completion: an agent thinking about a large file is also silent.
• A detached session keeps the size of the last attached client, or 80x24 if no client ever attached. TUIs look wrong after reattaching until they redraw. aggressive-resize on helps when several clients are attached.
• Scrollback is held in memory per pane and is lost when the server stops.
• Nothing survives a reboot.
• There is no event for a finished or parked agent, and no shared state between sessions.

The guide puts the practical ceiling at about four agents. The crystl claims (approval cards, typed transcripts, persistent history) are the vendor's own description and are not shown in use.