fix(terminal): only forward scroll to Claude while it tracks the mouse - #498
Merged
Merged
Conversation
Claude 2.1.280 renders inline by default: no alt screen, no mouse tracking, transcript in real scrollback. The version-only gate still sent every wheel tick and touch swipe as SGR reports, which Claude ignores, so scrolling a Claude session was dead while codex (routed locally) worked. Gate forwarding on the server-recorded cliMouseTracking flag, which fullscreen mode (CLAUDE_CODE_NO_FLICKER=1) sets.
Ark0N
pushed a commit
that referenced
this pull request
Sep 28, 2026
…#498) - claude's declared-for-later wheelForward says the live rule in _shouldForwardWheelToApp is the version AND the server-published cliMouseTracking flag, so whoever wires the field up needs both Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Ark0N
pushed a commit
that referenced
this pull request
Sep 28, 2026
- _logScrollRouting() reports cliMouseTracking, the gate's new input, in both the de-dup signature and the console line (xterm's own mouseTracking stays 'none' for Claude, so it gave no reason for a no). - Restore two guard tests the new gate made vacuous: the local-scrollback opt-out footgun test and the codex/gemini "no version rescues it" fixtures now set cliMouseTracking: true, so removing the opt-out or re-adding codex to the gate fails again. - Update the comments and architecture-invariants lines that still described the version-only rule (wheel handler header, gate doc, the false paths of _maybePageCliTranscript, "holds a tracking mode on continuously"). - Name both fullscreen switches (CLAUDE_CODE_NO_FLICKER=1 and "tui": "fullscreen" in ~/.claude/settings.json) in the code comment, the invariants and the two wiki pages. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Owner
|
Merged, and it ships in 1.33.2. Thanks @JDProfresh. The tmux measurement table is what made this easy: inline Claude never turns mouse tracking on, so gating on the
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
On Claude Code 2.1.280, wheel and touch scrolling in a Claude session does nothing, while the same gesture scrolls a Codex session fine. Reproduced on iOS Safari; the desktop wheel takes the same path.
Cause
_shouldForwardWheelToApp()forwards every Claude session at or above 2.1.187 as SGR wheel reports, on the assumption that Claude pages its own transcript. That only holds in Claude's fullscreen renderer. Measured on 2.1.280 in a bare tmux:alternate_onmouse_any_flagmouse_sgr_flagCLAUDE_CODE_NO_FLICKER=1In the default inline renderer Claude never enables mouse tracking and keeps its transcript in real scrollback (the affected live pane had
history_size=1018), so the forwarded reports are ignored and the gesture is dead. This is the same failure #227 fixed for Codex.Fix
Forward only while the server-observed
cliMouseTrackingflag is true (already recorded by_recordStrippedMouseModeand used by_shouldReportMouseToClifor taps). Inline Claude now scrolls local scrollback like Codex; fullscreen Claude keeps forwarding. A stale-false flag after a server restart falls through to the existing PageUp/PageDown fallback (_maybePageCliTranscript), so the gesture is never dead.Docs describing the forwarding rule (
CLAUDE.md,docs/architecture-invariants.md, two wiki pages) are updated to match.Open question
The #144 and #205 work measured Claude panes with
history_size=0and verified forwarding against 2.1.202, which suggests Claude was running fullscreen there. I could not tell whether Claude's default renderer changed since then or those setups had fullscreen enabled. The fix does not depend on which, since it checks the live mouse-tracking state.Testing
test/terminal-touch-tap.test.ts(inline 2.1.280 does not forward; withcliMouseTrackingit does); existing forwarding fixtures now setcliMouseTracking: true.npm test: 8300 passed.