Short version. tmux new -A -s claude, run claude, detach with Ctrl+B then d. Add the config below so Shift+Enter, notifications and the mouse wheel work. To scroll up: PgUp or the wheel if Claude Code is in fullscreen rendering, tmux copy mode (Ctrl+B then [) if it is in the classic renderer.

Why run Claude Code inside tmux

Claude Code is a long-running terminal program. Started in a plain terminal or SSH session, it dies with it. Inside tmux it belongs to the tmux server on that computer, so you can detach, reconnect later and find it mid-task. Anthropic's Remote Control docs give the same advice: to keep a session running on a remote machine after you disconnect from SSH, start it inside tmux or screen.

The second reason is parallel work: one window or pane per agent, each in its own repository or worktree.

A minimal working setup

Install tmux with your package manager (brew install tmux, apt install tmux), then:

tmux new -A -s claude    # attach to "claude", or create it
claude                   # start the agent inside
# Ctrl+B then d          # detach; everything keeps running
tmux ls                  # list sessions
tmux attach -t claude    # come back

The prefix key is Ctrl+B; press it, release, then the command key. The ones you need: c new window, % split left and right, " split top and bottom, w pick a window from a list, , rename the window, d detach. Give each agent its own window, named after the project.

One clash: Claude Code uses Ctrl+B to background a running task. Its docs say tmux users press it twice.

A ~/.tmux.conf for Claude Code

# Documented by Anthropic for Claude Code
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

# Scrolling and input
set -g mouse on
set -g history-limit 50000
set -sg escape-time 10

# Colour and focus
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ',*:Tc'
set -g focus-events on

Apply it to a running server with tmux source-file ~/.tmux.conf. What each line does:

  • allow-passthrough on lets a program in a visible pane send escape sequences through tmux to the outer terminal. Per Anthropic's terminal configuration page, without it desktop notifications and the progress bar never reach your terminal.
  • extended-keys on and the extkeys feature let tmux tell Shift+Enter from Enter. Without them, the same page says, Shift+Enter submits instead of inserting a newline, even when the outer terminal supports it. Ctrl+J inserts a newline with no setup.
  • mouse on makes tmux capture the mouse (it is off by default). Claude Code's fullscreen docs say wheel scrolling inside tmux requires it.
  • history-limit is the number of lines kept per pane. The default is 2000, which an agent fills quickly.
  • escape-time is how long tmux waits after Esc to see whether it starts a key sequence. Esc interrupts Claude, so you want it short. tmux 3.5 lowered the default to 10 ms; setting it covers older versions. The tmux FAQ says zero is likely fine locally and a larger value suits slow networks.
  • default-terminal must be screen, tmux or a derivative; the FAQ offers screen-256color or tmux-256color.
  • terminal-overrides ',*:Tc' tells tmux the outer terminal supports 24-bit colour. Claude Code clamps itself to 256 colours inside tmux unless you also export CLAUDE_CODE_TMUX_TRUECOLOR=1; Anthropic's environment variable reference gives this pair. Skip both if your terminal lacks true colour.
  • focus-events on passes focus changes to programs that ask for them. Anthropic doesn't list it as required; treat it as optional.

Leave set-clipboard at its default, external: tmux can set your terminal's clipboard, and Claude Code writes selections to the tmux paste buffer when it runs inside tmux. The tmux wiki warns that on lets any program in a pane set your system clipboard.

Run /terminal-setup in the host terminal, not inside tmux; it needs to write the host terminal's configuration.

Scrolling: find out which renderer you're in

The answer changed in 2026: Claude Code now has two renderers, and each scrolls differently. Type /tui to see which one is active.

Classic renderer

The conversation goes into the terminal's native scrollback, which inside tmux is the pane history. Scroll with copy mode: Ctrl+B then [, move with the arrow keys or PageUp, press q to leave. Ctrl+B then PageUp enters copy mode already scrolled up a page. With mouse on, tmux's default wheel binding enters copy mode by itself. Search backwards with Ctrl+R, or ? with vi keys.

Fullscreen renderer

Fullscreen rendering draws on the alternate screen, like vim. It is a research preview, and Anthropic's docs list it as the starting renderer if you first used Claude Code on or after 6 May 2026 (with exceptions), so expect details to change. The conversation is no longer in tmux's history; the docs say tmux search can't see it. Instead:

  • PgUp and PgDn scroll half a screen inside Claude Code; the mouse wheel works when tmux has mouse on. On a MacBook keyboard, Fn with the up and down arrows sends them.
  • Ctrl+O opens transcript mode, with / to search. Pressing [ there writes the whole conversation into native scrollback, where tmux copy mode can search and select it until you leave with q.
  • /tui default switches back to the classic renderer, and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces it.

What is known to be awkward

  • Copy-mode workflows broke for some users. GitHub issue #60185 (open, May 2026) reports that output no longer reaches tmux's scrollback; #67289 (June 2026, closed as not planned) calls it an accessibility regression. The documented ways out are transcript mode's [ and /tui default.
  • Wheel scrolls the wrong thing. In #38810 (March 2026) a user found the wheel moving through input history instead of the conversation. Per the docs, without tmux mouse mode wheel events don't reach Claude Code.
  • Selecting text. In fullscreen, Claude Code captures the mouse: a drag selects inside Claude Code and copies on release. For a native selection hold Shift in most terminals (Option in iTerm2, Fn in Terminal.app), or set CLAUDE_CODE_DISABLE_MOUSE=1.
  • Flicker. tmux through the 3.6 series lacks synchronized output; 3.7 added it. Anthropic's advice is to upgrade tmux.
  • iTerm2's tmux -CC mode is incompatible with fullscreen rendering. Regular tmux inside iTerm2 is fine.

Knowing when Claude needs you

By default Claude Code sends desktop notifications only in Ghostty, Kitty and iTerm2, and inside tmux they need the passthrough line. Elsewhere, set "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json. tmux highlights a window that rang the bell in its status line, a serviceable marker for which agent wants something.

From a phone

Attaching from a phone SSH app works, with two catches. First, size: by default tmux sizes a window to the most recently active client, so the session shrinks to phone width and a split layout built for a desktop becomes unreadable. Use one pane per window and switch with Ctrl+B then w. Second, keys: every tmux command needs Ctrl+B, and scrolling needs PgUp or copy mode, so pick an app with Ctrl, Esc and arrow keys on its key bar.

How to run Claude Code from your phone compares the options, including Anthropic's Remote Control. Herdr is an alternative multiplexer that tracks whether each agent is working, blocked or done; Herdr vs tmux covers the trade-offs. Our own app, Melta, works with Herdr, not tmux.

Common questions

How do I scroll up in Claude Code inside tmux? In fullscreen rendering, PgUp or the wheel with set -g mouse on. In the classic renderer, tmux copy mode: Ctrl+B then [. /tui tells you which you have.

Why does Shift+Enter submit in tmux? tmux doesn't pass the modifier through by default. Add the two extended-keys lines, or use Ctrl+J.

Does Claude Code have a tmux integration? Two are documented: claude --worktree name --tmux creates a tmux session for a worktree, and agent teams, which are experimental and off by default, can give each teammate its own tmux pane.

What are the best practices for Claude Code in tmux? One named session, one window per agent, the config above, and a recent tmux. Check /tui before blaming tmux for scrolling.

Sources