A tmux Cheat Sheet for Long-Running Sessions (and AI Agents)

When you run something in a terminal over SSH, it's attached to that connection. Close the laptop, lose Wi-Fi, or let the connection time out, and the process dies with it. That's fine for a quick command. It's painful for a long build, a dev server, or an AI agent halfway through an hour of work.

tmux fixes it. It runs your terminal sessions on the server, independently of your connection. You detach, disconnect, go home, reconnect from a different device, and reattach — everything exactly where you left it, still running.

Here's what you need to know, without the hundred features you don't.

The one idea: the prefix key

tmux commands start with a prefix: press Ctrl+b, let go, then press the command key. So "Ctrl+b then d" means: hold Ctrl, press b, release both, press d.

Everything below is written as prefix + key.

Sessions: the part that makes it all work

tmux new -s work          # start a new session named "work"
tmux ls                   # list sessions
tmux attach -t work       # reattach to "work"
tmux kill-session -t work # end it

Inside a session:

Keys	Action
`prefix` `d`	Detach — leave the session running, go back to your normal shell
`prefix` `s`	Switch between sessions from a list
`prefix` `$`	Rename the current session

The core workflow: SSH in, tmux attach -t work (or tmux new -s work the first time), work, prefix d to detach, disconnect. Next time, tmux attach -t work. That's 90% of the value.

A shortcut many people use: tmux new -A -s work — attach if it exists, create it if it doesn't.

Windows: tabs inside a session

Keys	Action
`prefix` `c`	Create a new window
`prefix` `n` / `p`	Next / previous window
`prefix` `0`–`9`	Jump to window by number
`prefix` `,`	Rename the window
`prefix` `&`	Close the window (asks first)

A common layout: window 0 for the editor or agent, window 1 for the dev server, window 2 for a free shell.

Panes: split the screen

Keys	Action
`prefix` `%`	Split left/right
`prefix` `"`	Split top/bottom
`prefix` arrow keys	Move between panes
`prefix` `z`	Zoom a pane to full screen (and back)
`prefix` `x`	Close the pane

prefix z is the most useful one: zoom into a pane to read it properly, then zoom back out.

Scrolling back

tmux has its own scrollback. prefix [ enters copy mode; use the arrow keys or Page Up/Down to scroll, q to exit. With mouse mode on (below), the scroll wheel just works.

A small config that makes it pleasant

Put this in ~/.tmux.conf:

set -g mouse on                  # scroll, click panes, resize with the mouse
set -g history-limit 50000       # much more scrollback (default is 2000 lines)
set -g base-index 1              # number windows from 1, matching the keyboard
setw -g pane-base-index 1
set -g renumber-windows on       # no gaps when you close a window
set -sg escape-time 10           # no lag after pressing Esc (important for Vim users)
bind r source-file ~/.tmux.conf \; display "Reloaded"

Reload with tmux source-file ~/.tmux.conf, or prefix r once the binding exists.

The bigger scrollback matters more than it looks: an agent or a build can produce thousands of lines, and the default loses the start of them.

Running an AI agent in tmux

tmux is the simplest way to keep an agent like Claude Code running on a remote machine while you're away. Some habits that help:

One session per project. tmux new -s billing, tmux new -s website. Each agent gets its own session with its own working directory, and tmux ls shows what's running at a glance. If you run several agents in parallel on one repo, pair this with git worktrees — see Running Claude Code Agents in Parallel With Git Worktrees.

Give the agent a window, and yourself another. Window 1 runs the agent; window 2 is a shell where you can check git status, tail logs, or look at the running app without interrupting it.

Keep the dev server in its own window rather than letting the agent start it in the background, so you can see its output and restart it yourself.

Check in from your phone. Any SSH app plus tmux attach puts you into the live session from a phone or tablet. prefix z to zoom the agent's pane makes it readable on a small screen. (How to Use Claude Code From Your Phone compares this with the other options.)

Use mosh on flaky connections. mosh in place of SSH survives network changes and sleep; combined with tmux, reconnection is seamless.

Remember what tmux doesn't do. It keeps processes running while you're disconnected. It doesn't survive the server rebooting, and it doesn't keep your environment consistent over time. For that, the machine itself has to be persistent and maintained — see How to Run Claude Code on a Remote Server. And make sure the agent doesn't sit waiting at a permission prompt for hours; Running Claude Code Unattended covers that.

Quick reference card

SESSIONS                          WINDOWS                    PANES
tmux new -s NAME   new            prefix c   new             prefix %   split ⇆
tmux ls            list           prefix n/p next/prev       prefix "   split ⇅
tmux attach -t N   attach         prefix 1-9 jump            prefix ←→  move
prefix d           detach         prefix ,   rename          prefix z   zoom
prefix s           switch         prefix &   close           prefix x   close
                                                              
SCROLL: prefix [  (q to exit)     prefix = Ctrl+b

Alternatives

GNU screen is the older tool that does the same core job, and it's preinstalled on many servers. Zellij is a newer alternative with on-screen hints, which some people find easier to learn. The session-survives-disconnect idea is identical in all three; learn whichever one is on the machines you use.

EasySpawn keeps Claude Code running in a persistent cloud workspace — no tmux or server upkeep required — and lets you reconnect to the same session from the browser, your phone, or SSH. See how it works or join the waitlist.