You ask Claude Code to refactor a module. It says "this will take a few minutes." You close your laptop and head out for coffee. You come back, open the lid, and your SSH session is dead, your terminal is empty, and Claude Code never finished — because the moment your connection dropped, the agent that was running on your remote machine got killed along with it.
If you've felt that exact frustration, the fix has existed for over a decade and it's called tmux. This post is the shortest possible introduction I can write — four commands, one analogy, and a workflow that lets you walk away from your AI agent without losing its work.
What tmux actually does
tmux (terminal multiplexer) is a small program that runs on your server or remote Mac and keeps your terminal session alive even when you're not connected to it.
The TV analogy is the easiest one I know:
- Plain SSH is live broadcast. If you leave the room, you miss it. If the cable goes out, the show is gone.
- tmux is recording. The show keeps running on the box at home. When you come back, you reconnect and pick up exactly where you left off.
For Claude Code, this is the difference between "I asked it to do something big and lost an hour of work" and "I asked it to do something big and watched the result roll in from my phone three hours later." The agent doesn't care that you walked away. tmux is what makes that possible.
The three layers (skim this and move on)
You don't need to memorize this. Just know these words exist:
| Layer | Mental model | What it is |
|---|---|---|
| Session | A desk | Your workspace. You can have a "work" session and a "personal" session running side by side. |
| Window | A browser tab | Tabs inside a session. Switch with one key. |
| Pane | A split view | Splits inside a window. Useful on big screens, painful on phones. |
For mobile work, one session, one or two windows, no panes is all you need. Pane splits are nice on a 27-inch monitor and miserable on a 6-inch screen.
Install it (one minute)
tmux runs on the server side — the machine you're SSH'ing into. You don't install anything on your phone or iPad. On a Mac:
# 1. Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 2. Install tmux
brew install tmux
# 3. Verify
tmux -V
If you see something like tmux 3.6a, you're done.
On Linux servers, replace step 2 with sudo apt install tmux or sudo dnf install tmux depending on your distro.
The four commands you actually need
I have been using tmux daily for years and I genuinely use one command 95% of the time. Here are all four anyway, in increasing order of "I actually need this."
1. Create a session
tmux new -s work
work is just a name. Pick anything. When tmux starts, you'll see a green status bar at the bottom of your terminal — that's how you know you're inside a tmux session.
2. Detach (leave the session running)
While inside tmux, press:
Ctrl+b then release then press d
The Ctrl+b is called the prefix key. You always press it, release it, then press a second key. d is for "detach."
You'll drop back to your normal shell prompt. The tmux session is still running in the background — your processes are still working, your scrollback is preserved, Claude Code is still doing its thing. You just stepped out of the room.
You can now safely close your laptop, kill your SSH connection, lose your Wi-Fi, whatever. The session lives on the server.
3. Re-attach (come back to it)
tmux attach -t work
Boom — you're back. Same screen, same scrollback, same running processes. If Claude Code finished while you were gone, you'll see its output waiting for you. If it's still running, you'll see it in real time.
4. The one command I actually use
tmux new -As work
The -A flag means "attach if a session named work already exists, otherwise create a new one." This is the only tmux command I type. It's idempotent: it always puts me into the work session, regardless of whether one was already there.
If you only memorize one thing from this post, memorize that.
A real-world workflow
Here's how I actually use this with Claude Code on a normal day:
Morning, at home, on my Mac:
ssh me@myserver
tmux new -As work
claude
I open Claude Code inside the tmux session and ask it to do something that'll take a while — refactor a service, write tests, audit a dependency. Then I close my laptop and leave for the train.
On the train, on my phone or iPad:
ssh me@myserver
tmux attach -t work
I see exactly the screen Claude Code was looking at when I left. If it's still working, I can watch the progress. If it's finished and waiting on input, I can answer right there. If I need to think about something, I Ctrl+b d to detach again and the session keeps running while I read a book.
Evening, back at the Mac:
tmux attach -t work
Same session, same context. I never lost a thing.
This pattern — start a long-running agent task on one device, monitor and approve from another — is the killer use case for AI coding agents on mobile. tmux is what makes it work.
A small gotcha when switching devices
If you attach from your phone while your Mac is also still attached to the same session, tmux will resize the display to the smaller screen. Annoying. The fix:
tmux attach -d -t work
The -d flag detaches whoever was previously attached, so only your current device sees the session. I use this constantly when bouncing between Mac and iPad.
Common keys (for after you're comfortable)
All tmux commands start with Ctrl+b, then a second key. Press them in sequence, not together.
| What you want | Keys |
|---|---|
| Detach |
Ctrl+b then d
|
| List sessions |
Ctrl+b then s
|
| New window |
Ctrl+b then c
|
| Next window |
Ctrl+b then n
|
| List windows |
Ctrl+b then w
|
| Help |
Ctrl+b then ?
|
For a phone or small tablet, I'd skip pane splitting entirely and just use windows. Two windows — one for Claude Code, one for git status and file pokes — is enough for almost everything.
Where this falls apart on mobile (and what to do about it)
Honest take: tmux's prefix-key model is great on a real keyboard and frustrating on a touchscreen. Tapping Ctrl+b then n on a soft keyboard means hunting for the Ctrl key, then the b, then the n, every single time you want to switch windows. After about ten of those, you start questioning your life choices.
This is exactly the problem I ran into when I started doing serious AI agent work from my phone. I ended up building MT — Mosh Terminal, a $14.99 one-time iOS terminal whose entire bottom action bar is just one-tap tmux operations — split, switch, detach, the works — so the prefix-key gymnastics disappear on mobile. It also gets a system push notification the moment Claude Code needs you, so you don't have to keep checking. I'll write more about that in a later post; for now just know that the option exists if mobile tmux ever drives you up a wall.
You don't need any of that to make tmux work, though. The four commands above are the whole game.
Wrap-up
tmux is a "recording device" for your terminal. Once your sessions live on the server and not on your local connection, the question of "what happens if my laptop sleeps while Claude Code is working" stops being scary.
The cheat sheet you actually need:
| Action | Command |
|---|---|
| Start (or rejoin) | tmux new -As work |
| Step out |
Ctrl+b then d
|
| Come back | tmux attach -t work |
| Steal session from another device | tmux attach -d -t work |
That's it. Try it once tonight: open a tmux session on your dev box, run a long task inside it, close your laptop, and reconnect from your phone an hour later. The first time it works you'll wonder how you ever lived without it.
→ If you want the mobile side of this story, the app I built for it is MT — Mosh Terminal on the App Store.
I'm a solo iOS developer. I write about gadgets and dev tools at jaga-farm.com. MT — Mosh Terminal is my first App Store release. Find me on X at @jaga_farm.
Top comments (0)