tmux keeps terminal sessions running on a machine after you disconnect, and splits one terminal into windows and panes. That suits Claude Code well: a long task keeps going when you close your laptop or lose SSH, and you can watch several sessions at once.

Every shortcut below starts with the prefix, Ctrl-b by default: press Ctrl-b, let go, then press the key.

Sessions

Windows

Panes

Scrolling and copying

With set -g mouse on (below), the mouse wheel scrolls too.

Starter ~/.tmux.conf

set -g mouse on                        # scroll, click panes, drag borders
set -g history-limit 50000             # keep long Claude Code output
set -sg escape-time 10                 # pass Esc through quickly (see below)
set -g base-index 1                    # number windows from 1
setw -g pane-base-index 1              # number panes from 1
set -g default-terminal "tmux-256color"

# For Claude Code (see below)
set -g allow-passthrough on            # let notifications through tmux
set -s extended-keys on                # let Shift+Enter reach Claude Code
set -as terminal-features 'xterm*:extkeys'

Reload it without restarting: tmux source-file ~/.tmux.conf.

Why run Claude Code inside tmux

Without tmux, Claude Code belongs to your terminal window. When the window closes or an SSH connection drops, the system sends a hang-up signal (SIGHUP) to everything running in it, and Claude Code exits mid-task. Anything it started goes with it: a test run, a build, a dev server.

With tmux, the programs belong to the tmux server, not to your window. Your terminal is only a viewer. If the viewer goes away, tmux keeps Claude Code running, and you reattach later to find it where it got to.

Isn’t claude -c enough? It brings back the conversation, but not the work that was in flight. Whatever Claude was doing when it was killed stops part-way, so you have to check what finished and ask it to continue. tmux avoids the interruption in the first place.

Where tmux runs matters. tmux protects against losing the connection, not against the machine stopping. If tmux runs on your laptop, closing the lid still pauses everything. For tasks that should keep going while you’re away, run tmux and Claude Code on a machine that stays on, such as a remote server or VM, and connect to it over SSH.

Using it with Claude Code

Keep long tasks alive. Start Claude Code inside a session, then detach:

tmux new -s claude
claude
# ...give it a task, then press prefix d to detach
tmux attach -t claude   # later, from any terminal or SSH login

Code on one side, shell on the other. Run claude in one pane and split with prefix % for a shell beside it, to run tests, check git diff or watch logs while Claude works. Use prefix z to zoom whichever pane you’re reading.

Parallel sessions without clashes. Give each Claude Code session its own git worktree and its own tmux window, so they never edit the same files. Claude Code can create the worktree for you. Open a new window with prefix c and run:

claude -w feature   # start Claude Code in its own worktree named "feature"

Or set one up yourself with git worktree add ../myapp-feature -b feature, then run claude inside it.

Make Esc respond instantly. Esc interrupts Claude Code while it’s working, and pressing Esc twice on an empty prompt opens the rewind menu to go back to an earlier point. By default tmux waits 500 ms after Esc to see whether it starts a longer key sequence, which makes both feel laggy. set -sg escape-time 10 in ~/.tmux.conf fixes it.

Multi-line prompts. Type \ then Enter, or press Ctrl-j, to add a new line; both work in tmux with no setup. Shift+Enter needs the extended-keys lines in the config above, and run /terminal-setup in Claude Code outside tmux, not inside it.

Know when Claude needs you. In Claude Code’s /config, set notifications to the terminal bell (the preferredNotifChannel setting, value terminal_bell). When Claude finishes or needs input in a background window, tmux flags that window in the status bar. Desktop notifications need allow-passthrough on in the config above.

Pick up where you left off. If a pane or session was closed:

Run a one-off prompt in a background window. claude -p runs non-interactively and prints the answer:

tmux new-window -d -n summary 'claude -p "Summarise the changes on this branch" > summary.txt'