Fullscreen rendering

Fullscreen rendering is an alternative way for the Claude Code CLI to draw itself. Instead of appending output to your terminal's scrollback, it takes over the terminal's alternate screen buffer the way vim, less or htop do, and only draws the messages currently in view. The payoff: no flicker, memory that stays flat however long the session runs, and proper mouse support.

"Fullscreen" here has nothing to do with maximising the window. It describes who owns the drawing surface, and it works at any window size.

Note: Fullscreen rendering is a research preview, so behaviour may shift between releases. You can switch either way at any time with /tui fullscreen and /tui default.

You will notice the biggest improvement in terminals where throughput is the bottleneck: the VS Code integrated terminal, tmux and iTerm2. If your scroll position leaps to the top while Claude works, or the screen flashes as tool output streams in, this is the fix.

Turning it on and off

/tui fullscreen writes the tui setting (see the settings reference) and relaunches the CLI with your conversation intact. The relaunch carries across:

• The conversation as you see it. If you used /rewind, you come back at the rewound point, not the longer transcript on disk; rewinding to before your first message gives you an empty conversation.
• Your permission mode and effort level.
• The model you last chose with /model.
• --allowed-tools and --disallowed-tools rules, plus --agent, --agents, --append-system-prompt and --system-prompt-snapshot.

Some session restrictions cannot be passed to a fresh process: a --system-prompt replacement, a --tools allowlist, --setting-sources, or deny/ask rules added for this session only by a hook or SDK permission update. In those cases you get Cannot switch renderers in this session with the reasons, and nothing is switched or saved.

/tui clears CLAUDE_CODE_NO_FLICKER from the relaunched process so the setting it just wrote actually takes effect.

In screen reader mode the classic renderer is always used (except in attached background sessions), and /tui fullscreen explains this rather than switching.

Which renderer you start in

Attached background sessions from agent view are always fullscreen; screen reader sessions are otherwise always classic. For everyone else, Claude Code works down this list and uses the first match:

1. CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 or CLAUDE_CODE_NO_FLICKER=0 is set: classic.
2. CLAUDE_CODE_NO_FLICKER=1 is set: fullscreen.
3. Fullscreen was switched off on this machine after a failed start: classic.
4. You are in iTerm2's tmux -CC integration, or connected over SSH to Claude Code running on Windows: classic.
5. You have saved a tui setting: whatever it says.
6. Your session does not fetch feature flags and the startup offer has been retired on this machine: classic.
7. Your session does not fetch feature flags and this machine's first ever launch was v2.1.239 or later: fullscreen.
8. Your session fetches feature flags and you first used Claude Code on or after 6 May 2026: fullscreen.
9. Anything else: classic.

Sessions that skip feature-flag fetching include those via Amazon Bedrock, Google Vertex AI and Microsoft Foundry, and any session with telemetry disabled.

If you land in classic with no saved tui setting, a startup dialog may offer the switch. Accepting relaunches exactly like /tui fullscreen and saves the setting once the new session has started cleanly. Not now stops the offer on this machine, and it also stops by itself after appearing on three launches.

What feels different

The quickest tell: the input box stays pinned to the bottom while Claude works. Because the conversation lives in the alternate buffer rather than native scrollback, three habits change:

Mouse support

With mouse capture on, you can:

• Click inside the prompt to place the cursor.
• Click entries in the / command list or @ file list to accept them (hover highlights).
• Click options in select menus: permission prompts, /model, /config and similar.
• Toggle items in multi-select menus and click the submit button; clicking a free-text row such as Other focuses its input (v2.1.208+).
• Click a value in /config to change it and wheel through the list (v2.1.271+).
• Wheel-scroll long select menus while the pointer is over them (v2.1.280+).
• Use the scrollbar that appears beside long lists in /skills, /mcp and /plugin (v2.1.281+): click the track or drag the thumb. Arrow buttons at each end scroll a row at a time and repeat when held (v2.1.286+).
• Click a ↑ N more or ↓ N more row to jump to that end of a list (v2.1.286+).
• Click a collapsed tool result to expand the call and its output together; click again to fold it. This also works for ! shell command output, including the live progress row (v2.1.257+), and for dim Message from @<sender> lines from teammates or other agents.
• Hold Cmd (macOS) or Ctrl (elsewhere) and click a URL to open it in the browser, or a file path from tool output to reveal it in your file manager. A plain click does not open links.
• Drag to select; double-click selects a word (file paths and full URLs select as one unit, iTerm2-style); triple-click selects a line.
• Scroll with the wheel.

Some quirks with link clicking:

• On Linux and WSL, opening a file path needs a file manager that implements the org.freedesktop.FileManager1 D-Bus interface.
• Windows UNC paths such as \\fileserver\team\notes.md render as plain text on purpose, since opening one could leak your Windows credentials to that host.
• Some macOS terminals forward Cmd-click to the app as a plain click. Ghostty and Warp on macOS are detected, and a plain click on a link opens it there.
• In VS Code and other xterm.js terminals, Claude Code lets the terminal's own link handler do the work.

Copying

Selections copy to the clipboard as soon as you release the mouse. Turn this off with Copy on select in /config; then copy with Ctrl+Shift+C, or Cmd+C in terminals that speak the kitty keyboard protocol (kitty, WezTerm, Ghostty, iTerm2). With a selection active, Ctrl+C copies rather than cancelling.

Shift plus the arrow keys extends a selection; Shift+↑/Shift+↓ scroll when you reach the edge, and Shift+Home/Shift+End extend to the line ends.

What happens to the selection when you press other keys:

• Esc does its usual job (interrupt, close dialog) and the highlight stays.
• PgUp, PgDn, Ctrl+Home, Ctrl+End, and arrow/Home/End combined with Shift, Alt/Option or Cmd/Win/Super leave it alone.
• Anything else, including bare arrows, Enter and typing, clears it.
• A key you bind to selection:clear always clears it. That action ships unbound; see keybindings.

Scrolling

History survives compaction: Claude works from the summary, but every earlier message stays scrollable, however many times the session compacts.

MacBook keyboards lack dedicated paging keys, so use Fn with the arrows (Fn+↑ is PgUp, Fn+↓ PgDn, Fn+← Home, Fn+→ End). Ctrl+Fn+→ never reaches Claude Code on macOS, so to get back to the bottom click the jump button, wheel down to the end, or rebind scroll:bottom. All scroll actions, including unbound half-page and full-page variants, are listed in keybindings.

When you are scrolled up, a dim header row shows the most recent prompt above the viewport. Click it to jump there.

Auto-follow

Scrolling up pauses auto-follow so new output does not yank you back down, and the view also stays put when a reply finishes. A floating Jump to bottom button appears, with a count such as 2 new messages as output arrives. Click it, press Ctrl+End or wheel to the bottom to resume. On macOS the button's hint suggests clicking or Fn+↓ instead of Ctrl+End; rebind scroll:bottom and it shows your chord everywhere. In narrow terminals the hint shortens rather than wrapping.

To disable auto-follow entirely, set Auto-scroll to off in /config. Dialogs that need an answer, such as permission prompts, still scroll into view.

Wheel speed

The terminal has to forward mouse events. In iTerm2 that is a per-profile switch: Settings → Profiles → Terminal → Enable mouse reporting. Without it the wheel, click-to-expand and selection all do nothing, while PgUp/PgDn still work.

If scrolling crawls, your terminal is probably sending one event per notch (the VS Code terminal does; Ghostty and iTerm2 with faster scrolling already amplify). Multiply it:

export CLAUDE_CODE_SCROLL_SPEED=4

Any positive value up to 20 is accepted, including fractions such as 0.5 to tame trackpads in terminals that already accelerate. 3 matches Vim's feel.

Prefer to tune by feel? /scroll-speed opens a dialog: scroll to test, ←/→ to adjust, r to reset to the detected default, Enter to save to ~/.claude/settings.json. It steps in whole numbers up to 10, with quarter steps down to 0.25 on terminals that support finer control. Its ceiling is 10, so a higher environment value shows (and saves) as 10. It is not available in the JetBrains terminal.

Claude Code also speeds up when you spin the wheel fast. For a constant rate per notch, set "wheelScrollAccelerationEnabled": false in settings (v2.1.174+).

JetBrains terminals

The JetBrains terminal emits scroll events far faster than other emulators, so Claude Code uses its own handling there and ignores CLAUDE_CODE_SCROLL_SPEED. Version 2025.2 also has wheel bugs (phantom arrow keys, reversed direction) that Claude Code detects and works around, showing a one-time hint. Upgrading to 2025.3 or later gives the smoothest result.

Searching and reviewing

Ctrl+O toggles transcript mode, which adds less-style keys:

Your terminal's own search cannot see the alternate buffer. From transcript mode you can hand the text back:

• [ writes the whole conversation, tool output expanded, into native scrollback. Now Cmd+F and tmux copy mode work. It lasts until you leave transcript mode with Esc or q; long sessions may pause briefly while it writes.
• v writes it to a temp file and opens $VISUAL or $EDITOR.

For a calmer view showing only your last prompt, a one-line summary of tool calls with diffstats, and the final answer, run /focus. It persists across sessions until you run it again.

In fullscreen, /diff opens a side panel so you can watch changes build up while Claude works. Details are in interactive mode.

Redrawing and clearing

/clear starts a new conversation. If the screen looks garbled, Ctrl+L redraws it without touching the conversation or your input. Cmd+K does the same where the terminal passes it through; iTerm2 and Terminal.app clear their own screen on Cmd+K, and Claude Code notices and repaints.

Older behaviour, in case you are on an older build: from v2.1.260 to before v2.1.280, Ctrl+L cleared the screen in fullscreen; before v2.1.238, pressing Ctrl+L twice within two seconds ran /clear.

tmux

Fullscreen works inside tmux with three caveats.

1. Mouse mode. Wheel scrolling needs set -g mouse on in ~/.tmux.conf; otherwise tmux eats wheel events. Keyboard paging works regardless, and Claude Code hints at startup if mouse mode is off.
2. No tmux -CC. iTerm2's tmux integration draws panes as native splits, which breaks the alternate buffer and mouse tracking (dead wheel, and double-click can corrupt the terminal). Plain tmux inside iTerm2 is fine.
3. Flicker on older tmux. Releases up to and including the 3.6 series lack synchronised output, so redraws can flicker more. Upgrade tmux or give Claude Code its own tab.

See terminal configuration for the passthrough and extended-keys lines you also want.

Keeping native text selection

Mouse capture is the usual friction point, especially over SSH or in tmux: your selection lives inside Claude Code, so the terminal's copy-on-select, tmux copy mode and Kitty hints cannot see it.

Claude Code puts the selection on the clipboard itself, choosing a route by platform:

A toast after each copy tells you which route was used. Long selections inside GNU screen copy correctly from v2.1.219. Some terminals block OSC 52; in iTerm2 enable Settings → General → Selection → Applications in terminal may access clipboard, which /terminal-setup does for you.

For a one-off native selection, hold a modifier while dragging so the terminal handles it:

Claude Code's on-screen hint shows the right key, or lists candidates over SSH and tmux when it cannot tell.

To give up mouse capture permanently but keep flicker-free rendering:

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

Keyboard scrolling still works; you lose click-to-place, click-to-expand, link clicks and wheel scrolling. A middle ground is CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1: the wheel still scrolls, but clicks, drags and hover do nothing inside Claude Code (you still hold your terminal's modifier for native selection, and right-click or middle-click paste still work). If both variables are set, CLAUDE_CODE_DISABLE_MOUSE wins.

Troubleshooting

Leftover fragments on screen

Fullscreen only sends cells that changed. Windows Terminal and other ConPTY hosts sometimes merge those writes wrongly and leave stale text until you resize. Force a full repaint every frame:

$env:CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT = "1"; claude

On macOS or Linux prefix the command with CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT=1. Windows already does this automatically for background sessions and agent view.

"Claude Code's fullscreen renderer didn't finish starting last time"

A fullscreen session counts as started once it has drawn a frame and either stayed up 10 seconds or been ended with /exit, Ctrl+C or Ctrl+D. If one crashes before that, your next session opens in classic:

• After one failed start you see the "didn't finish starting last time on this machine" message, and fullscreen is retried next session.
• After two, you see "has repeatedly failed to start on this machine", and classic sticks (silently) until you update Claude Code or run /tui fullscreen.

Run /tui to confirm: the Current renderer line mentions the failed start. /tui default keeps classic and saves it without relaunching.

How the counting works:

• Only sessions that were fullscreen because of the tui setting, the startup dialog, or the default count.
• CLAUDE_CODE_NO_FLICKER=1 forces fullscreen even after failures and is never counted.
• Counts are per Claude Code version and reset after a successful start.
• If you accepted the startup dialog and the relaunch crashed, neither message appears and the dialog is not offered again on that version.

Builds before v2.1.236 kept trying fullscreen after a failed start.

Reporting problems

Use /feedback, or open an issue on the claude-code GitHub repository, including your terminal name and version. When you switch back with /tui default you may get an optional prompt asking why; type a reason and Enter, or Esc to skip.

Background sessions from agent view or claude attach always render fullscreen; neither the tui setting nor CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN affects them.

Related

• Terminal configuration
• Keybindings
• Interactive mode
• Accessibility
• Agent view