The problem
If you run Claude Code or Codex in a browser-based terminal (like Cockpit), your session lives inside a WebSocket connection. When that connection drops, browser tab closed, laptop lid shut, phone screen locked, network hiccup, everything dies. The agent stops mid-task. Your context is gone. You start over.
Cockpit compounds this with a 15-minute idle session timeout. If the agent is thinking quietly, running tools, processing files, and you're not clicking around in the Cockpit UI, your session gets terminated automatically, taking the agent with it.
The solution
tmux is a terminal multiplexer that runs on the server, not in your browser. Your agent session runs inside tmux. The browser terminal just shows you a view of it, like a window into a room that exists independently of whether you're looking.
Without tmux
The agent process is a child of the browser terminal. Close the tab → kill the process. One device, one session, no recovery.
With tmux
The agent runs inside a server-side tmux session. Close the tab, switch devices, lose network, tmux keeps running. Reconnect and attach.
Setup
tmux runs on the server, the always-on machine where your agent CLI lives. Your laptop, phone, or tablet is just the client connecting to it. Everything in this Setup section is configured on the server. See Installing tmux if you don't have it yet, and Connecting from different devices for the client side.
Configure tmux
Create ~/.tmux.conf on your server. This sets up mouse support, better scrollback, a readable status bar, and a built-in help popup at Ctrl+B H.
Full config available in the GitHub repository.
Auto-attach on terminal open
Add this to ~/.bashrc (or ~/.zshrc on macOS, where zsh is the default). It attaches to (or creates) a tmux session named main whenever you open a new terminal on the server. Use whichever condition matches how you connect:
Pick one, or keep both, since the conditions don't overlap. The -z "$TMUX" guard prevents nested tmux sessions when you re-attach.
Fix the Cockpit idle timeout (Cockpit only)
Skip this step if you connect over SSH. By default, Cockpit terminates idle web sessions after 15 minutes, exactly long enough to time out while the agent is working quietly. Disable it:
Then restart Cockpit: sudo systemctl restart cockpit.service
Installing tmux on the server
Check whether it's already there with tmux -V. You want 3.2 or newer for the display-popup help binding; older versions still work if you remove that one block from .tmux.conf.
| Server OS | Install command |
|---|---|
| Debian / Ubuntu / Raspberry Pi OS | sudo apt update && sudo apt install tmux |
| Fedora / RHEL 8+ / Rocky / AlmaLinux | sudo dnf install tmux |
| CentOS 7 / older RHEL | sudo yum install tmux |
| Arch / Manjaro | sudo pacman -S tmux |
| openSUSE | sudo zypper install tmux |
| Alpine | apk add tmux as root (Alpine has no sudo by default, use doas if configured) |
| macOS (as the server) | brew install tmux (needs Homebrew) |
| FreeBSD | sudo pkg install tmux |
| Windows (WSL2 Ubuntu/Debian) | sudo apt install tmux inside the WSL shell |
Native Windows has no tmux. tmux is POSIX-only. On a Windows server, run your agent CLI and tmux inside WSL2, or use a separate Linux/macOS box as your always-on host. PowerShell and CMD can be SSH clients, but they can't host the tmux session.
macOS as a server: works fine, but enable Remote Login in System Settings → General → Sharing so you can SSH in, and disable App Nap on Terminal so the box doesn't throttle background work. A Mac mini or always-plugged-in laptop with "prevent sleep when display is off" is a reasonable host.
Connecting from different devices
Once tmux is set up on the server, anything that can open a shell on it, SSH, mosh, or Cockpit's web terminal, works as a client. The auto-attach snippet drops you straight into the running session, so the client doesn't need to know anything about tmux.
macOS
Built-in Terminal.app or iTerm2 + ssh user@server. OpenSSH ships with macOS, no install needed.
Tip: set up ~/.ssh/config with a Host alias so you can run ssh box from any folder.
Windows
Windows Terminal with the built-in OpenSSH client (ssh user@server) is the modern path. PuTTY works too. WSL gives you a Linux shell that can both SSH out and host tmux.
Linux desktop
Any terminal emulator + ssh. Same pattern as macOS. GNOME Terminal, Konsole, Alacritty, Kitty, Wezterm, all fine.
iOS / iPadOS
Blink Shell (paid, polished, mosh support) and Termius (free tier) are the two solid choices. Both handle the on-screen Ctrl key needed for tmux's Ctrl+B prefix.
Android
Termux (free, install from F-Droid, the Play Store version is unmaintained) gives you a real shell with pkg install openssh. Termius is the easiest GUI option.
ChromeOS
Enable the Linux container (Settings → Developers → Linux development environment), then sudo apt install openssh-client and use ssh like any Linux desktop. The Secure Shell extension also works without enabling Linux.
Browser (Cockpit)
Open https://yourserver:9090 and use the Terminal app. Works from any device with a browser, including phones, but apply the Cockpit timeout fix above.
Flaky networks (any device)
Install mosh on both the server and the client (apt/dnf/brew install mosh; Blink Shell has it built in), then use mosh user@server instead of ssh. Mosh survives network changes and sleep, a good companion to tmux on cellular or while moving between Wi-Fi networks.
Mosh also needs UDP ports 60000–61000 open inbound to the server, open them in your firewall (and any cloud security group) or you'll see "mosh: connect failed".
Phone keyboards and the Ctrl key: tmux's prefix is Ctrl+B, which most mobile SSH apps expose via a software toolbar above the keyboard. If you'd rather use a different prefix, add set -g prefix C-a (and unbind C-b / bind C-a send-prefix) to ~/.tmux.conf, Ctrl+A is a common alternative that's easier on some layouts.
Key bindings
All tmux commands start with the prefix Ctrl+B, press and release it, then press the next key. Ctrl+B H shows this as a popup in your terminal.
| Ctrl+B then C | New window |
| Ctrl+B then , | Rename current window |
| Ctrl+B then W | List all windows (interactive) |
| Ctrl+B then 1–9 | Switch to window by number |
| Ctrl+B then N / P | Next / previous window |
| Ctrl+B then % | Split left/right |
| Ctrl+B then " | Split top/bottom |
| Ctrl+B then ↑↓←→ | Move between panes |
| Ctrl+B then Z | Zoom pane to full screen (toggle) |
| Ctrl+B then [ | Enter scroll mode (use arrows/PgUp, Q to exit) |
| Ctrl+B then D | Detach, session keeps running |
| Ctrl+B then H | Help popup (from this config) |
| Ctrl+B then ? | Full built-in keybinding list |
Suggested window layout
Name your windows so the status bar tells you what's running at a glance. Use Ctrl+B , to rename.
1: claude
Your active agent session (Claude Code, Codex, or another CLI). This is where you work.
2: logs
journalctl -f or tail -f on scheduler or app logs.
3: shell
Free shell for quick commands, file checks, or running builds.
Coexisting with scheduled agent sessions
If you run automated agent sessions (cron-based check-ins, email processing, transcript analysis), they can conflict with your interactive session, competing for CPU and trying to process the same data at the same time.
Add this function to your scheduler to detect an active interactive session and skip the automated wake:
The pane_current_command tmux format string returns the name of the running process, no need to parse ps aux. Add the command name of any other agent CLI you run. A tmux socket is a separate server, so a session started with -L agent is invisible to plain tmux commands; list every socket you use in SESSIONS.
If your scheduler sends work into one long-lived session instead of starting a new one, skipping is not enough. Use a single-flight lease: the scheduler holds a lock while a wake runs, and only an explicit done step from the session releases it. The persistent attendant section of the autonomy kit covers the full pattern.
Getting notified when a session needs input
tmux can highlight a tab when the process in it goes quiet, a reliable signal that something has finished and is waiting for you. This uses monitor-silence, which fires after a window has produced no output for a set number of seconds.
Add these lines to your ~/.tmux.conf:
The monitor-silence 20 value is seconds. Bump it up if it fires too often during normal processing pauses.
Why silence, not activity? monitor-activity fires on every byte of output, too noisy for agent sessions that stream continuously. monitor-silence fires only when output stops, which is a much better proxy for "waiting for you." While a session is running it outputs constantly; when it hits a prompt or finishes, it goes quiet.
Survive reboots: supervise the session
tmux keeps a session alive when you disconnect, but not when the server restarts. On a Linux server with systemd, run the tmux session as a user service. systemd starts it at boot, restarts it if it crashes, and can cap its memory so one runaway tool cannot take down the machine.
systemd watches the tmux server, not the agent. Keep this session to one window that runs only the agent. When the agent exits, its window closes, the tmux server exits, and systemd starts it again. Open logs and shells on a different tmux server (plain tmux, not tmux -L agent), not as extra windows or sessions here: anything else on this server keeps it alive after the agent dies, and nothing restarts it.
Pin the conversation. claude --continue and codex resume --last pick the most recent conversation in the directory, so after a crash the service could resume a different session you opened there. This launcher keeps one conversation ID and always resumes it:
Make it executable with chmod +x. The launcher relies only on two Claude Code errors, not on where Claude stores conversations: --resume exits at once with "No conversation found" for an ID it has not saved, and --session-id exits at once with "already in use" for one it has. So a failed first start is created again under the same ID, and a resumed session that crashes ends the launcher, and systemd starts it again. Keep set -m: without it, the resumed claude runs as a child of the launcher shell, and pane_current_command reports sh. The scheduler check above and the reboot check below would then miss the running agent. Before you enable the service, run claude once by hand in the project folder and accept the folder-trust prompt; otherwise the service waits at that prompt. Codex cannot choose an ID up front: start the session once by hand, write its session ID to the same file, and replace the last line with exec /path/to/codex resume --no-daemon "$(cat "$id_file")". Without --no-daemon, Codex can run tools in a shared app-server outside this unit's limits.
If you use the auto-attach snippet above, point it at this session, and attach without exec: tmux -L agent attach -t agent || echo "agent session is not running: systemctl --user status agent-session". If the service is down or waiting to restart, the attach fails and you keep a normal login shell to repair it. When you detach, you return to that shell. Do not let a login shell create the session with new-session -A; systemd owns it, and a session created by a shell runs outside the service and its memory limits.
Size the memory limits to your machine. MemoryHigh slows the session down before MemoryMax stops it. On a small server, keep subagent fan-out small (two or three) and move heavy compute to another machine.
Prove it with a real reboot. A unit that starts by hand can still fail at boot. Reboot once, then confirm that the boot ID changed (cat /proc/sys/kernel/random/boot_id), the service is active, the agent itself is running (tmux -L agent list-panes -t agent -F '#{pane_current_command}' shows claude or codex), the memory limit applies (systemctl --user show agent-session -p MemoryMax), and the agent's tool processes run inside the unit (systemd-cgls --user-unit agent-session.service). On macOS, use a launchd agent with KeepAlive. On Windows, run the session inside WSL2 and start the distribution at logon.
Check in from your phone without SSH
Claude Code and Codex can both expose a running session to their own apps, so you can read and answer it from a phone without a terminal. Use this on top of tmux, not instead of it: tmux and the service still keep the process alive.
Codex remote control runs tools in its app-server daemon, not in the --no-daemon session above. If you use it, run the daemon as its own supervised service with its own memory limits. Both features change quickly. Check --help on your installed version before you build on them. Anyone who can reach the remote session can run commands on your server, so protect the account that controls it.
Common pitfalls
The first session after setup won't be in tmux
The .bashrc change only applies to new terminal sessions opened after saving the file. Close your current terminal tab and open a fresh one to get tmux.
display-popup requires tmux 3.2+
Check your version with tmux -V. If you're on an older version, remove the bind H display-popup ... block from .tmux.conf and use Ctrl+B ? for help instead.
Name your windows
Use Ctrl+B , to name each window. The status bar shows all window names at once, without names, you'll end up with a row of identical bash entries.
tmux survives, but the server has to stay on
Sessions persist across browser disconnects, not server reboots. A Pi or always-on server works for this; a laptop that gets shut down does not. To survive reboots, supervise the session.
Related skills
An agent that keeps working after you close the tab
A few config changes. Runs on any headless Linux, macOS, or BSD server with tmux. Connect from a Mac, Windows, Linux, ChromeOS, iOS, or Android client.
View on GitHub