Tmux runs your AI coding agents in named, detachable sessions that survive a closed terminal or a dropped SSH connection. You get one window holding many agents, send-keys to type into any of them from a script, and capture-pane to read one back. That combination is why people use it. Before you build any of it by hand, check the built-in path: recent versions of Claude Code can create the worktree and the tmux session for you with claude --worktree --tmux. This guide covers that first, then everything it doesn’t reach, then the point where tmux itself stops.
Why tmux and agents go together: A coding agent is a long-running process that wants to keep talking to a terminal. Three properties of tmux match that shape: It survives disconnection. The tmux server owns the pty, not your terminal window. Close the window, lose your SSH link, put the laptop to sleep: the agent keeps working and is still there when you reattach. It holds many sessions in one window. Four agents become four named sessions you switch between with a keystroke, instead of four windows you hunt for in the app switcher. It’s scriptable from outside. Any shell, anywhere, can type into a running agent or read its screen. No IPC to build, no API to wire up.
The built-in flag, before you build anything: Claude Code ships with this wired up for the single-agent-on-a-branch case. Two flags, from claude --help on a recent version: -w, --worktree [name] Create a new git worktree for this session (optionally specify a name); --tmux Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use --tmux=classic for traditional tmux. So the whole “isolate this task, give it its own session” move is one command: claude --worktree --tmux. Or name the worktree: claude --worktree auth-refactor --tmux. Two details matter before you rely on it. --tmux errors without --worktree, so it’s 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 is nicer to look at and means the tmux commands in the rest of this page have nothing to attach to. Pass --tmux=classic when you want real tmux underneath, which you do if you plan to script against the session. For a single agent on a single branch, that’s the answer. Use it and skip ahead.
What it doesn’t do: run several agents in one session, lay out panes so you can watch them, let you type into a running agent from a script, tell you which agent is waiting on you, or set any of this up on a remote box over SSH. Those are the rest of this guide, and each one is where people end up writing tmux by hand. More on the worktree half of that flag in git worktrees for parallel development.
Session per project, named by project: The organizing rule that keeps this usable: one tmux session per repo, named after the repo. Not per task, not per agent. Tasks come and go; the project is the stable thing. Start a detached session in a project directory: tmux new-session -d -s api -c ~/code/api. Attach to it (creates it if it doesn’t exist): tmux new-session -A -s api -c ~/code/api. -A is attach-or-create. It makes a single command safe to run repeatedly, which is what you want in a shell function: # ~/.zshrc agent() { local dir="${1:-$PWD}" local name="$(basename "$dir" | tr . -)" tmux new-session -A -s "$name" -c "$dir" }. Session names can’t contain . or : (tmux uses them as target separators), hence the tr. Then tmux ls becomes a real inventory: $ tmux ls api: 3 windows (created Fri Jul 31 09:12:04 2026) web: 2 windows (created Fri Jul 31 09:40:11 2026) infra: 1 windows (created Fri Jul 31 11:02:55 2026). Add a bit more with a format string: tmux list-sessions -F '#{session_name} windows=#{session_windows} attached=#{session_attached}'. A layout for watching several agents: Inside a session, give each agent its own window, named for the task: tmux new-window...
Source: Hacker News · Summarized by HeadlinesBriefing