Claude Code in tmux: scrolling, focus and display fixes

How you scroll Claude Code in tmux depends on which renderer it uses. In fullscreen rendering, add set -g mouse on to ~/.tmux.conf so the mouse wheel reaches Claude Code, or press PgUp: tmux copy mode only sees the current screen. In the classic renderer, the conversation is ordinary tmux history, so Ctrl+b [ and a bigger history-limit do the job.

Type /tui in Claude Code and it prints which renderer is active. Every setting below comes from Anthropic's pages on terminal configuration and fullscreen rendering, the tmux manual and tmux's own source for the defaults, all read on 24 October 2026. Starting several agents in tmux is a separate job, covered in running multiple Claude Code sessions in tmux; this page is about what goes wrong on screen afterwards.

A ~/.tmux.conf for Claude Code#

set -g mouse on
set -g history-limit 50000
set -g focus-events on
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ',*:Tc'
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Load it into the running server with tmux source-file ~/.tmux.conf. Some lines need one more step: default-terminal applies to windows you open afterwards, the tmux manual says to detach and reattach after changing focus-events, and tmux applies terminal-overrides to a client when it attaches. The sections below say what each line fixes.

Why can't I scroll up in Claude Code in tmux?#

Because in fullscreen rendering the conversation isn't in tmux's history at all. Fullscreen draws on the terminal's alternate screen, the way vim and htop do, so tmux copy mode and your terminal's scrollbar only ever see what is on screen. Anthropic's fullscreen page has a table of who starts where: most people who first used Claude Code on or after 6 May 2026 start in fullscreen, and a saved tui setting or the CLAUDE_CODE_NO_FLICKER variable overrides it.

Scrolling in fullscreen rendering#

1. Add set -g mouse on to ~/.tmux.conf and reload it. Without mouse mode, wheel events go to tmux instead of Claude Code. Claude Code prints a one-time hint at startup when it finds tmux with mouse mode off.
2. Or use the keyboard, which works either way: PgUp and PgDn move half a screen, Ctrl+Home jumps to the start and Ctrl+End back to the latest message. On a MacBook, Fn+↑ and Fn+↓ send PgUp and PgDn.
3. To search, press Ctrl+o for transcript mode, then /. Pressing [ in transcript mode writes the whole conversation into the terminal's normal scrollback, where tmux copy mode and your terminal's search can find it until you leave transcript mode.

The wheel keeps working in your other panes after this change. tmux's default wheel binding passes the wheel to a program that uses the alternate screen or asked for the mouse, and enters copy mode for anything else, such as a shell. A drag in a shell pane now starts tmux's own selection rather than your terminal's.

Scrolling in the classic renderer#

The classic renderer prints the conversation into the terminal like any command-line program, and Anthropic's docs say it "keeps the conversation in your terminal's native scrollback so Cmd+f and tmux copy mode work as usual". So the tmux keys apply:

1. Ctrl+b [ enters copy mode. Arrow keys and PgUp scroll, q leaves. Ctrl+b PgUp enters copy mode and goes up a page in one step.
2. Search with Ctrl+r in emacs keys, tmux's default, or ? if your mode-keys is vi. tmux picks vi keys by itself when $VISUAL or $EDITOR contains "vi".
3. Raise history-limit. tmux keeps 2,000 lines per pane by default, and a long Claude Code session runs past that. The 50,000 above is our choice, not tmux's: every pane keeps its own history, so the number costs memory per pane. Before tmux 3.7 a new limit only reached panes opened after the change.

To change renderer, run /tui default for classic or /tui fullscreen for fullscreen. Claude Code relaunches the session in the other one.

Copying text out#

In fullscreen rendering, Claude Code takes the mouse, so a drag selects inside Claude Code and copies when you let go. Inside tmux it also writes to tmux's paste buffer, which Ctrl+b ] pastes. For your terminal's own selection, hold Shift while you drag (Option in iTerm2, Fn in Terminal.app). CLAUDE_CODE_DISABLE_MOUSE=1 gives the mouse back to the terminal for the whole session, and you lose wheel scrolling inside Claude Code for it. That trade comes up most when tmux runs on a server, the setup in Claude Code over SSH.

If you use iTerm2's tmux -CC integration, don't turn fullscreen on there. Anthropic's page says the mouse wheel does nothing in that mode and a double-click can corrupt the terminal; Claude Code starts in classic rendering under tmux -CC unless you set CLAUDE_CODE_NO_FLICKER=1. Plain tmux inside iTerm2 is fine.

Why does Claude Code flicker in tmux?#

A program that redraws the whole screen can be caught halfway through a frame. Terminals avoid that with synchronized output, and tmux added it in version 3.7, released on 26 June 2026. Anthropic's docs say tmux through the 3.6 series doesn't implement it, and that Claude Code checks for support at startup and uses it when it's there.

1. Run tmux -V. On 3.6 or older, upgrade. The tmux server that is already running keeps the old version until it exits.
2. Switch to fullscreen rendering with /tui fullscreen. Anthropic suggests it whenever the display flickers or the scroll position jumps, because it sends less to the terminal on each update.
3. Or run Claude Code in its own terminal tab, outside tmux.

Why doesn't Ctrl+B work in Claude Code in tmux?#

Ctrl+B is two things at once: tmux's prefix key, and Claude Code's key for moving a running command or agent to the background. tmux gets the first press. There are three ways round it.

1. Press Ctrl+B twice. tmux's default bindings send the second press on to the program, and Anthropic's docs tell tmux users the same.
2. Press Ctrl+X Ctrl+B instead. Anthropic's keybindings reference lists it as a second default for the same action, task:background.
3. Move tmux's prefix. The example in the tmux manual:

set -g prefix C-a
unbind C-b
bind C-a send-prefix

With that, Ctrl+A becomes the key you press twice inside Claude Code, where it moves the cursor to the start of the line. What happens to a command once it is in the background, and how /tasks stops it, is in Claude Code background tasks.

The same clash shows up in fullscreen's transcript mode, where Ctrl+b scrolls up a full page. b does the same without touching the prefix, and Space pages back down.

Notifications, focus and Shift+Enter#

set -g allow-passthrough on is for notifications. Anthropic's terminal page says that without it, desktop notifications and the progress bar "never reach the outer terminal". With on, tmux lets them through only while the pane is visible; all lets them through from hidden panes too. Claude Code sends desktop notifications by itself only in Ghostty, Kitty and iTerm2; in other terminals, "preferredNotifChannel": "terminal_bell" in your settings rings the bell instead.

set -g focus-events on passes focus changes from your terminal to the program in the pane. It is off by default, so a program inside tmux never hears that you switched away. Claude Code cares about that: Anthropic's interactive-mode page says the one-line recap you see when you come back to a session is prepared while the terminal is unfocused.

The two extended-keys lines come from Anthropic's tmux section. Without them, Shift+Enter in tmux sends the message instead of starting a new line. Ctrl+J adds a new line everywhere, with or without them; it and the rest of Claude Code's keys are in our shortcuts cheat sheet.

Why do Claude Code's colours look washed out in tmux?#

Claude Code limits itself to 256 colours whenever $TMUX is set, because, as Anthropic's environment variable reference explains, tmux doesn't pass 24-bit colour through unless it is told to. To turn true colour on:

1. Add set -ga terminal-overrides ',*:Tc' to ~/.tmux.conf. tmux's FAQ also gives set -as terminal-features with RGB for tmux 3.2 and later.
2. Set CLAUDE_CODE_TMUX_TRUECOLOR=1 in your shell profile, or under "env" in ~/.claude/settings.json. Any value that isn't empty turns it on, 0 and false included; unset it to go back to 256 colours.
3. Detach and reattach, because tmux applies the override when a client attaches, then start claude.

default-terminal matters for the rest of the display. The tmux manual says it must be screen, tmux or a name derived from them. Prefer tmux-256color: tmux's FAQ says that with a screen name tmux turns italics off, because the screen description gets italics wrong. If your system's terminfo has no tmux-256color (it ships with modern ncurses), use screen-256color instead.

How Shuriken does it#

Shuriken shows each agent's work as a chat in the app rather than in a terminal, so tmux's history limit, copy mode and prefix key never sit between you and the conversation. You scroll it like any other page, on your computer or your phone. When you want Claude Code's own screen, a chat tab's Open in terminal resumes that same chat with claude --resume in a terminal tab inside Shuriken. If you like how a terminal reads, Terminal look (Settings › Appearance › Style) sets the whole app in a monospace face with › prompts. Download Shuriken to try it with your own Claude Code sign-in.