How to set up Claude Code in tmux

Updated October 31, 2026 · 4 min read

Claude Code runs in tmux with no setup, but tmux blocks its notifications and Shift+Enter until you add four lines to ~/.tmux.conf and run tmux source-file ~/.tmux.conf. After that, give each session its own window and git worktree, and tmux keeps them all running when you close the terminal.

Get Ambient Free for macOS 14 and later.

Add these lines to tmux

Put this in ~/.tmux.conf, then run tmux source-file ~/.tmux.conf to apply it to the running server:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Line	What it fixes
`allow-passthrough`	Notifications and the progress bar reach your outer terminal instead of stopping at tmux.
`focus-events`	tmux tells Claude Code when you enter or leave the pane. More on focus events.
`extended-keys` and `extkeys`	tmux can tell Shift+Enter from Enter, so Shift+Enter inserts a newline instead of sending your prompt.

Without the last two lines you can still add a newline with Ctrl+J, or by typing \ and pressing Enter. If you use /terminal-setup, run it in your terminal outside tmux, because it writes to that terminal's own configuration.

Start one window per session

Name a tmux session for your agents and give each Claude Code session a window and a worktree, so their edits don't collide:

tmux new-session -d -s agents -n auth 'claude --worktree feature-auth'
tmux new-window -t agents -n cache 'claude --worktree fix-cache-bug'
tmux attach -t agents

The repository needs at least one commit first. Close the terminal and the sessions keep running. tmux attach -t agents brings them back, and Ctrl+b w lists every window.

Know which pane needs you

tmux shows one screen at a time, so a session waiting in another window is easy to miss. With "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json, tmux flags the window that rang the bell in its status line. The tmux notifications guide covers that and a hook that messages tmux.

Ambient records the pane each agent runs in and shows the most urgent session at the notch. A click on the island, the banner or the menu bar row selects that exact pane. Codex and Gemini CLI sessions in tmux work the same way.

Stop babysitting terminals.

Free for macOS 14 and later. Works with Claude Code, Codex and Gemini CLI.

Get Ambient

Common questions

Do I need tmux to run Claude Code?

No. Claude Code works in any terminal. tmux helps when you want several sessions in one place, or sessions that survive closing the terminal.

Why does Shift+Enter send my prompt in tmux?

tmux can't tell Shift+Enter from Enter until extended keys are on. Add set -s extended-keys on and set -as terminal-features 'xterm*:extkeys' to ~/.tmux.conf, or press Ctrl+J for a newline.

Does Claude Code keep running after I close the terminal?

Inside tmux, yes. The tmux server keeps the session alive, and tmux attach brings it back.

Sources

Configure tmux, Claude Code docs
tmux manual, OpenBSD

More guides: Claude Code notifications in tmux · Multiple Claude Code sessions on Mac