Close the window. Keep the agent.
A three-hour Claude Code session should not depend on a terminal tab staying open. Two small config blocks make every window you open land in tmux, where agents keep running and can be driven by name. There is also a prompt that makes the change for you.
The most expensive keystroke in agentic work is ⌘W. You close what looks like a spare tab and it was the one running a two-hour migration. Or the terminal app updates itself overnight and restarts. Either way the shell gets a hangup signal, the agent inside it dies, and whatever it was holding in context goes with it.
The fix is older than every tool in the session. tmux runs your shells inside a background server, so the window becomes a view onto the work instead of the place it lives. Nothing here is new. What is new is how much it matters once the thing in the shell is an agent that runs for hours instead of a command that runs for seconds.
The window is not the session
tmux splits a terminal into two parts. The server is a background process that owns the shells and everything running in them. A client is whatever window you are looking through. Close the window and its client detaches. The server does not notice, and neither does the agent.
That also means one session can have several viewers. You can attach to it from a second window, or over SSH from a laptop on the couch. Or something with no window at all can attach, which turns out to be the useful part.
A terminal window is a client. The tmux server owns the shells and everything running in them. Close a window and that client detaches. The agent inside never sees a hangup.
Make your terminal open straight into it
tmux only helps if you are actually in it. The usual failure is forgetting to start it before the session that turned out to matter. So take the choice away. Have your terminal app open every new window directly into a tmux session.
Scope it to one app. Editor terminals, SSH logins and scripts that start zsh should keep getting a plain shell. Otherwise VS Code opens into tmux and every scripted zsh -c tries to attach to something. macOS sets __CFBundleIdentifier to the bundle ID of the app that launched the shell. That is the most reliable thing to match on. TERM_PROGRAM is the fallback, but tmux overwrites it, so read either one from outside tmux.
Two checks keep it from looping or leaking. $TMUX stops a shell inside tmux from starting tmux again. The app check keeps editor terminals, SSH logins and scripts on a plain shell. -A attaches to main when it exists and creates it when it does not.
# >>> tmux-terminal >>>
# Only the terminal app named below opens straight into tmux.
# Find yours with: echo $__CFBundleIdentifier (run it outside tmux)
if [[ -z "$TMUX" && -o interactive && "$__CFBundleIdentifier" == "com.mitchellh.ghostty" ]]; then
exec tmux new -A -s main
fi
# <<< tmux-terminal <<<Swap the bundle ID for your terminal's. Common ones: com.apple.Terminal, com.googlecode.iterm2, com.mitchellh.ghostty, dev.warp.Warp-Stable. exec replaces the shell with tmux, so leaving tmux closes the tab cleanly instead of dropping you into a leftover shell. -A attaches to main if it exists and creates it if not. Put the block near the end of the file so Homebrew's PATH is already set when tmux starts.
A config that behaves
Out of the box, tmux ignores the scroll wheel, keeps only 2,000 lines of history, and pauses half a second after every Escape. Agent TUIs notice all three. Eleven lines fix it.
# >>> tmux-terminal >>>
set -g mouse on
set -g history-limit 100000
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -g escape-time 10
set -g focus-events on
set -g set-clipboard on
set -g status-right "#S %-I:%M %p"
# <<< tmux-terminal <<<mouse on lets you scroll and click panes. history-limit keeps a long agent transcript scrollable. escape-time 10 removes the lag that makes Escape feel broken in Claude Code and vim. set-clipboard lets copies made inside tmux reach the system clipboard. The rest is house style: windows numbered from 1, the session name and time in the corner. Apply it to a server that is already running with tmux source-file ~/.tmux.conf.
One session per project
Don't stack ten agents as tabs in main. Give each project its own named session, started in its own folder. tmux ls then becomes the dashboard: one line per thing that is running, each one reachable by name.
tmux new -d -s warrior -c ~/Code/warrior # start detached, in that folder
tmux ls # what is running
tmux attach -t warrior # look at it
# Ctrl-b d # step away, it keeps goingLet one agent drive another
Because sessions have names and live outside any window, a script or a second agent can type into one and read it back, with nobody attached. This is how we run multi-agent builds. One orchestrator hands prompts to Claude Code and Codex sessions by name and checks their output on a schedule.
Two details cost us an afternoon each. Send the text and the Enter as separate calls. In our builds a combined send often left the prompt typed but not submitted. And always pass -l, so tmux sends the string literally instead of parsing words in it as key names.
Text and Enter go as two calls. -l sends the string literally, so tmux does not try to read words like Enter or C-c inside it as key names. capture-pane -p prints what is on screen, so the orchestrator can read the reply without attaching.
# 1. type the text, literally
tmux send-keys -t warrior:1 -l 'run the e2e suite and report failures'
# 2. press Enter, as its own call
tmux send-keys -t warrior:1 Enter
# 3. read the screen back, blank lines dropped
tmux capture-pane -p -t warrior:1 | grep -v '^$' | tail -40If a capture comes back with garbled control codes, clear the pane with send-keys C-l and clear-history, then read it again. The orchestrator only sees what is on screen, so keep the agent's output tight.
Hand the setup to an agent
You can paste the two blocks above yourself. We hand it to Claude Code instead, with a prompt that does the edit the way an edit to someone's shell config should be done. It finds the terminal it is running in and backs up both files. It wraps every change in marker comments, checks the syntax, and confirms that every tmux session running before the change is still running after it. It never kills a session.
The markers are the part that makes it safe to hand off. On a second run the agent replaces what is between them instead of appending a second copy. To undo the change, you delete one block.
Any agent prompt that edits shell config should carry all four. The markers are what make it safe to run twice: on a re-run, the agent replaces what is between them instead of appending a second copy.
Copy ~/Downloads/tmux-terminal-setup.md into the current directory,
read it fully, and execute every step. Back up first, never kill an
existing tmux session, and stop and report if you cannot positively
identify which terminal app this session is running in.Download the prompt to your Downloads folder first: intlo.com/news/tmux-terminal-setup.md. When it reports back, quit and reopen your terminal, then run echo $TMUX. Any output means you are in.
What it does not do
It does not survive a reboot. The tmux server is a normal process, and it dies with the machine. Sessions survive closed windows, app restarts and dropped SSH connections, but not a restart. If you need that, look at tmux-resurrect. Better still, have your agents write their state to disk.
Nested tmux needs care. If you SSH from one tmux into a machine that also opens into tmux, Ctrl-b goes to the outer one. Press it twice to reach the inner session, or give the remote machine a different prefix.
Scrollback works differently. With mouse mode on, the scroll wheel enters tmux's copy mode instead of the terminal's own scrollback. It feels wrong for a day and then it doesn't. Press q to leave copy mode.