Guide

Keeping a Claude Code session alive with tmux

A terminal agent lives inside a terminal. Close the window, lose the agent. Drop the SSH connection, lose the agent. tmux puts the agent inside a session the terminal merely looks at. The session keeps running when you look away. This is the setup we use on every agent Mac, with the exact commands.

Install and start

brew install tmux
tmux new -s agent

You are now inside a session named agent. Start the agent in it like any other command.

claude

For Codex, run its command instead. Everything on this page works the same way for either tool.

Detach and come back

Press Ctrl-b, release, then press d. The terminal returns to your shell and the agent keeps working in the background. To get back to it from any terminal on the machine, attach by name.

tmux attach -t agent

If you forget the name, list what is running.

tmux ls

Pick it up from your phone

Install an SSH client on your phone. Termius and Blink Shell are the common ones. Connect to the Mac and attach to the same session. You see exactly what the agent is doing and can type to it. Phone keyboards are poor for long prompts, so most people use the phone to check progress and answer a question, then do real work from a laptop.

For Claude Code specifically, Remote Control is a better phone experience than SSH. It attaches the Claude app to the running session with no terminal at all. The guide to running Claude Code 24/7 covers setting it up. tmux still matters underneath, because Remote Control attaches to a session that has to exist.

Make it comfortable

Two settings make tmux far easier for agent work. Put them in a file named .tmux.conf in your home folder.

set -g mouse on
set -g history-limit 50000

The first lets you scroll with a trackpad or finger. The second keeps enough output to read what the agent did an hour ago. Restart tmux after saving the file, or reload it from inside a session.

tmux source-file ~/.tmux.conf

Survive a reboot

tmux sessions live in memory. A restart clears them. For an unattended machine, the session should come back on its own. A LaunchAgent that runs at login does that. Save this as a file named dev.local.agent-session.plist in the LaunchAgents folder inside your home Library.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>dev.local.agent-session</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/sh</string>
    <string>-c</string>
    <string>/opt/homebrew/bin/tmux has-session -t agent 2>/dev/null || /opt/homebrew/bin/tmux new -d -s agent</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>StartInterval</key><integer>60</integer>
</dict>
</plist>

Load it once and it runs at every login and checks every minute after that.

launchctl load ~/Library/LaunchAgents/dev.local.agent-session.plist

This creates an empty session. It does not restart the agent inside it, on purpose. An agent that restarts itself into a half-finished task with no human awake is how you get surprises. Enable automatic login for the user so the LaunchAgent has a session to run in, then start the task yourself when you next attach.

Two sessions, two agents

Nothing stops you running Claude Code in one session and Codex in another on the same machine. Two Claude Code sessions on two repositories work too. Name them after the job.

tmux new -s api-refactor
tmux new -s ios-tests

Keep each agent in its own repository checkout so they do not edit the same files. Git worktrees make that cheap.

Frequently asked questions

Does tmux keep the agent running if the Mac sleeps?

No. tmux protects against the terminal closing and the connection dropping. Sleep freezes the whole machine, tmux included. Fix sleep separately with the power settings, then use tmux on top.

What is the difference between tmux and screen?

They solve the same problem. tmux is maintained, ships in Homebrew, and has the mouse and scrollback settings above. Use whichever you know. The commands differ but the idea is the same.

Can I see the agent's output from before I attached?

Yes. Scroll up inside the session. The history-limit setting controls how many lines are kept. With mouse mode on, scroll with a trackpad. Without it, press Ctrl-b then the left bracket key, scroll, and press q to leave.

Does this work on a hosted Mac?

Yes, and it is how our agent Macs are set up. A session named agent is created at login with the chosen agent running in it, and a Terminal window is attached to it on the desktop you open in your browser.