How to use tmux

How to leave work running on a machine you've walked away from — and pick it up from your phone.

Updated August 2026

Here's the problem tmux solves, in the shape you'll actually hit it.

You connect to a server, start something long — a build, a migration, an AI agent chewing through a codebase — and then your laptop sleeps, or the wifi drops, or you close the lid to go outside. When that connection dies, your shell gets a hangup signal, and everything running inside it dies with it. Not paused. Dead.

So you learn to keep the laptop open. Then you learn to keep it plugged in, because the screen has to stay on. Then it gets hot, and you're sitting next to it at 11pm watching output scroll past, because leaving would cost you the work.

tmux ends that. It runs a session on the *server*, not inside your connection. You attach to it to look, you detach to walk away, and the work never notices either. The laptop closes. The machine keeps going.

Sessions, windows, panes

sessionwindowpane

session (Project): One per thing you're working on. Survives when you disconnect.
window (Tab): One per job inside that project. Fills the screen.
pane (Split): A window cut in two, so you can watch both halves.

Sessions hold windows, windows hold panes. Most beginner confusion is not knowing which of the three a command is about to act on.

Almost every beginner mistake is a confusion between these three levels — killing a window when you meant a pane, or looking for a session that's actually a window inside another one. Hold the hierarchy and the commands stop being arbitrary.

For running agents, the mapping that works is one session per project and one window per agent. So a session called cueva holds windows named claude, kimi and opencode. Then tmux ls from your phone tells you what's alive in one line, which is exactly what you want to know when you're not at the desk.

The prefix key

Every tmux shortcut starts with a prefix: Ctrl + b. You press it, release it, and *then* press the next key. It isn't a chord — you're not holding Ctrl + b while pressing d.

That indirection exists because tmux sits between you and a program that has its own shortcuts. Without a prefix, tmux would swallow keys the program needed. It feels clumsy for about a day and then disappears.

The commands

tmux new -s namestart
Starts a new named session and drops you into it.
```
tmux new -s cueva
```
tmux new -A -s namestart
Attaches to that session if it exists, creates it if it doesn't. The one to actually memorise.
```
tmux new -A -s cueva
```
tmux lsfind
Lists every session running on this machine, and whether anyone is attached.
```
tmux ls
cueva: 3 windows (created Sat Aug 23 09:12:04 2026)
```
tmux attach -t namefind
Reconnects you to a session you left running.
```
tmux attach -t cueva
```
tmux rename-sessionmanage
Renames the current session, so `tmux ls` stays readable.
```
tmux rename-session -t 0 cueva
```
tmux kill-session -t nameWarning
Ends a session and everything running inside it. Name the target — never kill by pattern.
```
tmux kill-session -t cueva
```

tmux new -A -s name is the one to actually commit to memory. It attaches if the session exists and creates it if it doesn't, so you never have to remember which situation you're in — the same command is always right.

Note the one marked warning. Kill sessions by name, one at a time. Killing by pattern is how you take down four things when you meant to take down one, and tmux will not ask whether you're sure.

Detach is not quit

This is the idea the whole tool rests on, so it gets its own heading.

Ctrl + C kills what's running. Prefix then d leaves it running and hands you back your normal shell. When you detach, nothing stops — the session sits on the server with its processes still going, waiting for you to come back. You can close the terminal. You can shut the laptop. You can get on a plane.

If you take one thing from this guide, take that.

The shortcuts

Prefix means Ctrl + b. Press it, release it, then press the key after it.

Keys	Superpower
`Ctrlb`	The prefixEvery shortcut below starts with this. Press it, let go, then press the next key.
`Prefixd`	DetachLeaves everything running and hands you back your normal shell. The whole point of tmux.
`Prefixc`	New windowOpens another full-screen tab inside this session.
`Prefixnp`	Next / previous windowMoves between tabs. Prefix and a digit jumps straight to one.
`Prefix,`	Rename the windowName it after the job it's running, so the status bar tells you something.
`Prefix%`	Split left / rightCuts the window vertically. Prefix and " cuts it horizontally.
`Prefixs`	Session pickerA list of every session, to pick from. Use it when you've forgotten a name.
`Prefix[`	Copy modeHow you scroll back through output. Arrow keys or Page Up, then q to leave.

Reading output on a phone

Once your work lives on a server, you'll end up checking it from a phone, and two things change.

There's no scroll wheel. To look back through output you enter copy mode with prefix then [, move with the arrow keys or Page Up, and leave with q. Without it you can only see the last screenful, which is never the part you need.

And text selection fights you. Turning the mouse on in your config (set -g mouse on) makes tap-to-scroll work in most phone SSH clients, which is worth doing on day one. While you're there, raise the scrollback — set -g history-limit 50000 — because the default runs out fast when an agent is writing.

Check yourself

Only if you weren't in tmux.Without it, dropping the connection sends a hangup signal to your shell and everything inside it dies. Inside tmux, the session belongs to the server, not to your connection — it keeps going, and you reattach later.

Ctrl + C kills the program. Prefix d leaves it running.This is the single most useful distinction in tmux. Detaching is not quitting — it's walking away from a machine that keeps working.

Run tmux ls, then tmux attach -t <name>.Or skip the lookup entirely: tmux new -A -s cueva attaches if it's there and creates it if it isn't, so the same command works either way.

Prefix then [, then scroll. q to come back.That's copy mode. On a phone there's no scroll wheel to fall back on, so this is the only way back through output — which makes it the shortcut that matters most on a small screen.

That's enough tmux to stop losing work. The next step, once sessions are second nature, is wiring them to your phone properly — but the naming convention above is the part that has to come first, because everything else is built on being able to tell, from one line of output, what's running and where.