Guide covers running Claude Code agents in tmux sessions built to survive disconnects

A guide published at crystl.dev, currently on the Hacker News front page, lays out a practical playbook for running AI coding agents inside tmux: named sessions that outlive a dropped SSH connection, layouts for watching several agents at once, and send-keys as the scripting surface that turns a terminal multiplexer into a lightweight agent orchestrator.

Why tmux suits long-running agents

The guide's framing is that coding agents are long-running processes tethered to a terminal, and tmux matches that shape in three ways. The tmux server, not your terminal window, owns the pseudo-terminal, so closing the window, losing SSH or sleeping the laptop leaves the agent working until you reattach. Multiple agents become named sessions you switch between with a keystroke. And any shell, anywhere, can type into a running agent or read its screen, without building IPC or wiring up an API. According to the guide, that scriptability is what people end up building on, and the reason tmux keeps appearing in scripts that orchestrate agents.

The built-in Claude Code path

Before constructing any of it by hand, the guide points to what recent versions of Claude Code ship: claude --worktree --tmux creates a new git worktree and a tmux session for it in one command. Two caveats come with it. The --tmux flag errors without --worktree, so it is a worktree feature that happens to make a session, not a general session flag. And on iTerm2 it uses native panes instead of tmux, which looks nicer but means tmux commands have no session to target; pass --tmux=classic when you plan to script against the session.

That covers a single agent on a single branch. What it does not do, per the guide, is run several agents in one session, arrange panes so you can watch them, let a script type into a running agent, tell you which agent is waiting on you, or set any of it up on a remote box. Each gap is where hand-written tmux begins.

One session per repository

The organizing rule the guide recommends is one tmux session per repository, named after the repository — tasks are transient, the project persists. tmux new-session -A -s api -c ~/code/api attaches to a session or creates it, which makes a single command safe to run repeatedly and easy to wrap in a shell function. Session names cannot contain . or : because tmux treats them as target separators, so the example function transliterates dots to dashes. Under this convention, tmux ls becomes a real inventory of what is running.

Inside a session, windows suit background agents because they consume no screen space; panes are for the two or three you want visible at once. One trap is flagged: without -c '#{pane_current_path}' a new pane opens in the directory the session started in, and the agent you launch there points at the wrong repo. Two named layouts are suggested — tiled for an even grid, and main-vertical for one large driving pane with the rest stacked beside it — with a note that percentage values for main-pane-width require tmux 3.2 or newer; older builds take an absolute column count.

The config settings worth changing

The .tmux.conf section is presented as the delta from defaults once you are herding a fleet of agents: history-limit raised to 100000 for scrolling back through agent output; allow-rename and automatic-rename off, because agent TUIs like to set the terminal title and clobber your window names; monitor-activity on with visual-activity off to flag windows that produced output while you were elsewhere; escape-time lowered to 10, since the default delay for disambiguating the Escape key makes interactive TUIs feel sluggish; plus mouse support, 24-bit colour, 1-indexed windows and a five-second status refresh.

Scripting agents with send-keys

send-keys feeds keystrokes to a pane as though someone were typing, which makes it possible to drive an agent from cron, a git hook or even another agent. The guide ranks three failure modes by how often they bite. Bare arguments are interpreted as key names — Enter, C-c, Escape and Space are keypresses, not text — so literal prompts need -l, at the cost of sending the newline as a second call. A trailing semicolon is read as a tmux command separator and must be escaped. And agent input boxes that debounce or re-render can swallow an Enter arriving in the same frame as the text, so the reliable pattern sends the prompt, sleeps briefly, then sends Enter.

The guide is explicitly structured in three layers: the built-in flag, the manual tmux beyond its reach, and the ceiling at which tmux stops being the right tool.

Why it matters

Agent-driven development increasingly means several long-running agents working in parallel, often on remote machines over SSH. tmux is a near-zero-dependency substrate for that: process survival, a session inventory, and a scripting surface — send-keys paired with capture-pane for reading output back — just good enough for orchestration without custom infrastructure. Claude Code shipping first-class flags for it signals the workflow is moving from hack to default. Knowing the failure modes — key-name interpretation, semicolon escaping, paste debounce, wrong-directory panes, title-clobbering TUIs — is the difference between a fleet you can trust and one you babysit.