- Published on
Tmux and Claude Code: Sessions, Send-Keys, and the Ceiling
- Authors
- Name
- DeepHorus
tmux has quietly become the default substrate for running AI coding agents, and a newly circulating practitioner's guide lays out exactly how far the combination reaches before it breaks. The terminal multiplexer lets Claude Code and similar tools run inside named, detachable sessions that survive a closed window or a dropped SSH connection. Because the tmux server owns the pseudo-terminal rather than the user's terminal window, an agent keeps working while the laptop sleeps and is still there when the user reattaches.
The fit is structural rather than fashionable. A coding agent is a long-running process that wants to keep talking to a terminal, and tmux supplies three matching properties: survival across disconnection, many sessions inside a single window, and scriptability from any outside shell. That last property — the ability to type into a running agent or read its screen without building an IPC layer or wiring up an API — is why tmux keeps appearing in agent-orchestration scripts.
Claude Code already ships a built-in shortcut for the simplest case. Recent versions expose two flags, -w, --worktree [name] and --tmux, so a command such as claude --worktree auth-refactor --tmux creates a git worktree and a matching session in one step. Two caveats apply: --tmux errors without --worktree, and on iTerm2 it opens native panes instead of tmux, meaning the rest of a tmux-based workflow has nothing to attach to. Passing --tmux=classic forces real tmux underneath, which is required if the session will be scripted against.
Everything beyond that single-agent case still has to be written by hand. The built-in flag cannot run several agents in one session, lay out panes so they can be watched, type into a running agent from a script, report which agent is waiting on input, or configure any of it on a remote box over SSH. Each of those gaps is where users end up assembling tmux commands manually.
The organizing convention practitioners recommend is one tmux session per repository, named after the repository — not per task, not per agent, since tasks come and go while the project remains stable. Commands such as tmux new-session -A -s api -c ~/code/api are attach-or-create, making them safe to run repeatedly inside a shell function. Session names cannot contain periods or colons, because tmux reserves those characters as target separators.
From there, send-keys scripts input into any running agent and capture-pane reads one back, with a status-line monitor reporting state across the fleet. The approach has a documented ceiling, however: the described setup begins to strain at roughly four agents, where switching and monitoring overhead starts to outweigh the convenience of a single window. For single-agent, single-branch work, the built-in --worktree --tmux flag remains the recommended path, and the hand-rolled scaffolding is best reserved for the multi-agent, remote, and scripted cases it cannot reach.
