A Practical tmux Workflow for Claude Code

tmux and Claude Code fit together unusually well: long-running agent turns want a terminal that survives disconnects, and parallel sessions want named, stable places to live. This guide is a minimal tmux setup for agent work — the naming, layout, and monitoring habits that keep four sessions manageable, and an honest look at what tmux alone can't tell you.

Why tmux for agent sessions

• Sessions survive you. Close the terminal app, drop the SSH connection, reboot your laptop while a remote box keeps working — tmux attach puts you back in front of a Claude Code session that never noticed you left.
• Named windows are a free session list. The status bar shows every window's name at all times — the closest thing a terminal has to a dashboard.
• Scriptable layout. One shell function can create a window, cd to the right directory, and start claude — the same shape every time.

The layout: one window per session

The setup that scales best is boring: one tmux window per Claude Code session, named after the task, all inside one tmux session per machine or project.

# A window per task, named so the status bar reads like a task list
tmux new-window -n fix-auth   -c ~/code/myapp-fix-auth
tmux new-window -n onboarding -c ~/code/myapp-new-onboarding

# Start claude in each (or script it):
tmux send-keys -t fix-auth 'claude' Enter

Prefer windows over panes for the sessions themselves. Panes shrink each session's output to a fraction of the screen, and Claude Code's prompts, diffs, and plan output want the full width. Where panes shine is within a task: split a window to keep the session on one side and a shell for manual testing on the other (tmux split-window -h).

Two habits carry most of the weight. Rename the window when the task changes (tmux rename-window review-pr) — a status bar full of zsh, zsh, zsh tells you nothing. And if your windows are per-worktree (our git worktrees guide covers that setup), let the worktree's directory name double as the window name so every list agrees.

Remote machines: where tmux earns its keep

Running Claude Code on a remote box over plain SSH means one dropped connection kills the session mid-task. Inside tmux, the session keeps running; you reattach and scroll back through what happened while you were gone:

ssh devbox
tmux new -A -s agents   # attach if it exists, create if not
# ... start claude sessions in named windows ...
# connection drops, laptop sleeps, whatever —
ssh devbox
tmux attach -t agents   # everything still running

new -A makes the command idempotent — the same line works for first connect and every reconnect, which makes it a good SSH alias.

What tmux can tell you — and what it can't

With several windows running, the question becomes: which one needs me? tmux has two built-in signals, and both are weaker than they look:

# Flag windows with new output (the flag shows as # in the status bar)
setw -g monitor-activity on
set  -g visual-activity  off   # flag quietly; no message popup

# Or highlight on the terminal bell
setw -g monitor-bell on

monitor-activity fires on any output — a progress spinner counts — so with an active agent it's mostly noise. The bell is closer: Claude Code can ring the terminal bell when it finishes or needs attention (see /config), and tmux will mark the window. But a flag in the status bar still only says something happened. It doesn't say whether the session is blocked on a permission prompt, waiting on a plan approval, asking you a question — or just done. You still switch windows to find out.

Real state, not activity flags

For push-style signal, Claude Code's hooks fire on lifecycle events — Notification (Claude needs input) and Stop (Claude finished) — and can trigger a real macOS notification regardless of which tmux window is visible. For the aggregate view, we built AgentManager: a macOS menu bar app that shows every Claude Code session — every tmux window included — as a row with a status lamp: waiting for input, running, done, idle. Waiting rows say what kind of answer is needed — a yes/no approval, a plan review, or a multiple-choice question. One honest caveat: click-to-jump, which switches you straight to the right pane in iTerm2, Terminal.app, Ghostty, and VS Code-family editors, doesn't support tmux panes yet — tmux sessions are detected and tracked, but you still switch to them with tmux's own keys. The difference is that you now switch knowing exactly which window needs you and why. The floating window surfaces when a session starts waiting and hides when everything is clear, so the status bar flags become optional.

A minimal agent-friendly .tmux.conf

# ~/.tmux.conf — the agent-relevant parts only
set  -g history-limit 100000     # agent turns produce a lot of scrollback
setw -g monitor-bell on          # mark windows on bell
set  -g visual-activity off      # no popups; flags in the status bar only
set  -g renumber-windows on      # closed windows don't leave gaps
setw -g automatic-rename off     # keep your task names; don't auto-rename

Nothing exotic — the point is scrollback deep enough to review what an agent did, and window names that stay what you set them to.