How do you run Claude Code in tmux?
Short answer
Install tmux, start a named session with tmux new -s api, go to your project and run claude. Press Ctrl-b, then d, to detach: the agent keeps working. Reattach later with tmux attach -t api from any terminal or SSH login. On Linux, check that logging out does not kill your processes, and raise tmux's scrollback limit.
On this page
Why run Claude Code in tmux
Claude Code is a process in your terminal. Close the window, let the laptop lid drop on an SSH link, or lose the network, and the process that owns the conversation goes with it. tmux runs a small server that owns your terminals instead. Your terminal window becomes a client that can leave and come back, while the agent inside keeps running.
That matters more once you stop watching the agent. Anthropic's Remote Control, which lets you continue a local session from your phone, needs the claude process to keep running on your machine the whole time.3 Claude Squad is built on tmux sessions and git worktrees.6 Claude Code itself has a --tmux flag that creates a tmux session for a new worktree.2 And Orpheus's connector only sees agents that run inside tmux.
Install tmux and start a session
-
Install tmux
# macOS, with Homebrew brew install tmux # Debian or Ubuntu sudo apt install tmux # Fedora sudo dnf install tmux tmux -V -
Start a named session in your project
-snames the session and-csets its starting folder.1tmux new -s api -c ~/code/api claudeTo label the Claude conversation as well, start it with
claude -n api. The name shows in/resumeand the terminal title, andclaude --resume apibrings it back later.2 -
Detach and reattach
Press Ctrl-b then d to detach. The agent keeps going. Come back from any terminal on the machine, or over SSH:
# list sessions tmux ls # reattach to one tmux attach -t api # attach if it exists, create it if it does not tmux new -A -s api
Name sessions you can still read at ten
One session per project or task, named after it, is easier to live with than numbered windows. Use short lowercase names such as api-auth or web-billing. Avoid dots and colons, which tmux uses inside target names like api:1.0.1
| To do this | Run or press |
|---|---|
| See every session | tmux ls |
| Pick a session from a tree with previews | Ctrl-b then s |
| Rename the current session | Ctrl-b then $, or tmux rename-session -t old new |
| Check a session exists in a script | tmux has-session -t api (exit code 0 or 1) |
| Save a pane's text to a file | tmux capture-pane -p -S -3000 -t api > api.log |
| End a session and the agent in it | tmux kill-session -t api |
Keep agents running after you log out
Closing a terminal window or an SSH connection does not stop the tmux server. Two things can.
Linux: logind may kill your processes at logout
systemd's KillUserProcesses= setting decides whether a user's processes are killed when they log out. The upstream manual lists the default as yes and warns that it breaks tmux:4
The logind.conf manual says
“Note that setting KillUserProcesses=yes will break tools like screen(1) and tmux(1), unless they are moved out of the session scope.”
logind.conf, freedesktop.org · Checked .
Your distribution may set it differently, so check /etc/systemd/logind.conf. If it is on, turn on lingering, which keeps your user manager running after logout, and start tmux outside the login session's scope:5
Reboots end every session
tmux lives in memory, so a restart ends it. To bring agents back on boot, run a small script from a systemd user service on Linux or a launchd agent on macOS. Make it skip sessions that already exist, and start Claude Code with --continue, which loads the most recent conversation in that folder:2
launchd and systemd start jobs with a short PATH, so set PATH in the script or use the full path to claude. On Linux, the service also needs lingering on to start before you log in.
Scrollback and copy mode
tmux keeps 2,000 lines of history per pane by default (checked on tmux 3.6a). Long agent runs pass that quickly. Raise it in ~/.tmux.conf. The new limit applies only to windows created after the change.1
Press Ctrl-b then [ to scroll in copy mode, and q to leave it. If you run Claude Code in fullscreen mode, scroll inside Claude Code with PgUp and PgDn instead: Anthropic's docs note that tmux copy mode shows only the current viewport of a fullscreen app.7
Why remote tools need tmux
A tool that lets you watch or answer an agent from somewhere else needs a stable place to find it. A tmux session has a name, survives your terminal closing, and can be read and typed into by another program on the same machine. That is why several agent tools build on it rather than on terminal windows.
Orpheus works this way. Its connector runs on your machine, lists the tmux sessions your local policy file exposes, streams their output, and types text plus a fixed set of keys into them. It does not run other commands. An agent started in a plain terminal window, outside tmux, does not appear in Orpheus. See the setup guide for the policy file.
Common questions
Does closing the terminal stop Claude Code inside tmux?
No. The tmux server owns the session, so closing the window or dropping an SSH link only detaches you. The agent keeps running until you end the session, the machine restarts, or a logout policy on Linux kills your processes.
Should I use one tmux session per agent or one window per agent?
One named session per agent is easier to find, attach to and script, and tools that list tmux sessions show each agent separately. Windows inside one session work too, but their names are harder to see at a glance.
Can tmux bring my agents back after a reboot?
Not by itself. tmux keeps sessions in memory. A launchd agent or systemd user service can run a script at boot that recreates each session and starts Claude Code with --continue to load the last conversation in that folder.
Why can I not scroll back far enough?
tmux keeps 2,000 lines per pane by default. Set history-limit higher in ~/.tmux.conf, then open a new window, because the setting does not resize existing ones.
Sources
- tmux(1) manual pagetmux project, checked against tmux 3.6aUndated · Checked
- CLI referenceClaude Code docs, AnthropicUndated · Checked
- Continue local sessions from any device with Remote ControlClaude Code docs, AnthropicUndated · Checked
- logind.conf manual pagesystemd, freedesktop.orgUndated · Checked
- loginctl manual page (enable-linger)systemd, freedesktop.orgUndated · Checked
- Claude Squad README, How It Workssmtg-ai on GitHubUndated · Checked
- Manage multiple agents with agent viewClaude Code docs, AnthropicUndated · Checked