Tmux + Claude Code: Run an Agent in a Session That Survives Your Laptop Sleep

You are forty minutes into a Claude Code refactor. You close the laptop to grab coffee. You come back. The session is dead. You spend five minutes reorienting.

The fix is tmux. Not because tmux is fancy. Because the agent stays in the process tree of a long-lived shell that does not get killed when the laptop sleeps. Five minutes of setup, an hour a week back.

The Setup (Five Minutes)

You need tmux and a session name. That is it.

```bash

install

brew install tmux # macOS sudo apt install tmux # Debian/Ubuntu

create the session in your project dir

tmux new -s cc-frontend -c ~/code/frontend ```

Inside that session, launch Claude Code with --continue so the agent picks up the last conversation. Whole trick: --continue plus a shell that outlives your window manager.

The Three Commands You Actually Use

Detach, list, reattach. The muscle memory:

```bash

detach: Ctrl-b then d

or run it detached and let it work while you walk away

tmux new -d -s cc-backend -c ~/code/backend 'claude --continue'

see what is running

tmux ls

jump back in

tmux attach -t cc-frontend ```

The session outlives your shell, your SSH connection, and your laptop sleep. You close the lid at 14:32, wake the machine at 15:00, run tmux attach, and the agent is right where you left it — same scrollback, same context, same conversation. No five-minute penalty.

Gotchas I Hit So You Do Not Have To

1. macOS sleep pauses Claude, does not kill it. Tmux stays alive through sleep, but Claude Code freezes on M-series chips if the system does a hard suspend. Cold wake takes two to three seconds for Claude to resume generating on an M2 Pro. Acceptable.

2. The "I forgot to attach" problem. Drop this in your ~/.zshrc:

bash if [ -z "$TMUX" ] && [ "$(tmux ls 2>/dev/null)" ]; then echo "tmux: $(tmux ls)" fi

Every new terminal reminds you what is running in the background.

3. Never put Claude in a global tmux session. Project-specific names — cc-frontend, cc-backend, cc-infra — keep context from bleeding between repos. One session per repo, every time. Kill the old one with tmux kill -t cc-frontend when you are done.

4. SSH into a beefy dev box? Same trick. ssh devbox, then tmux new -d -s cc 'claude --continue'. Your laptop can stay closed for three hours and the agent is grinding on the upstairs GPU while you eat lunch. ssh devbox && tmux attach on the way back and the diff is ready.

Verify (Thirty Seconds)

Start a session. Close your laptop. Wait sixty seconds. Open the lid. Run tmux ls — the session is there. tmux attach -t cc-frontend — you are right back in the agent's scrollback. If it survives one sleep cycle, it survives the quarter.

The principle is the same as a hot-reload dev loop or a TDD red-green-refactor: kill the friction between intent and execution. The agent keeps grinding, you keep moving, and the laptop lid stops being a context boundary.

— Mr. Technology

*tmux 3.3+ (ships on every modern Linux/macOS, no extra runtime). Claude Code CLI --continue flag (Anthropic SDK 0.40+, June 2026). Tested on macOS 14.5 + Ubuntu 24.04. Pair with reattach-to-user-namespace on macOS for clipboard support inside tmux panes.*