Running Claude Code in tmux: A Practical Setup

EM Mini Pad is a small, heavy aluminium block with five keys, a knurled knob, USB-C and Bluetooth. A few navigation outputs can make a Claude Code session inside tmux easier to attach, inspect and leave running.

Why run Claude Code inside tmux?

tmux can detach a terminal program from the outside terminal and reattach it later, which protects the live process from a closed window or dropped remote connection. Claude Code also saves its conversation sessions for resume, so tmux preserves the running interface while Claude's own session history provides a separate recovery path.

That distinction matters. tmux is not a substitute for commits, worktrees or named Claude sessions. Create Git checkpoints and give parallel work separate directories before relying on terminal persistence.

How do you create a session that survives disconnects?

Start a named tmux session in the intended project directory, launch Claude Code inside it and detach with tmux's prefix command. Reconnect by listing sessions and attaching to the exact name. tmux keeps programs alive while its server and host continue running.

Claude Code's current CLI also offers a worktree option that can create a tmux session when explicitly requested. Read the installed CLI help before adopting that shortcut, since it is tied to worktree behavior and current terminal support.

How should scrollback and copy mode work?

tmux owns its own history and copy mode. Learn how to enter copy mode, search and exit without sending those keys to Claude. Mouse support can select panes and history, but terminal clipboard integration varies. Test copying a harmless response before relying on it for code.

Keep the agent stopped at a visible prompt while reviewing older output. Copy mode freezes your view, not necessarily the program, so new output may continue below what is displayed.

Which tmux settings deserve attention?

Claude's official terminal guide says tmux needs passthrough and extended-key settings for Shift-Enter, notifications and progress behavior. Add the documented lines to the tmux configuration and source the file into the running server. Test Shift-Enter separately from Enter.

The EM Mini Pad can carry attach-time navigation such as next window, previous window, copy mode and last window. Do not bind agent approval or Enter. Preserve the default recovery keys until the custom map works after a fresh tmux server start. Verify the working directory immediately after every reattach. A surviving terminal can still be attached to an old branch or host. Before asking Claude to edit, inspect Git status and the session name, then confirm the task still belongs in that directory.