[DOCS] [Fullscreen] Mouse-wheel scrolling in WSL2 under Windows Terminal and VS Code regressed in v2.1.172 and is now fixed in v2.1.179, but the docs do not mention WSL2 at all

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/fullscreen

Section/Topic

The "Mouse wheel scrolling" subsection under the "Fullscreen rendering" page (the section that begins ### Mouse wheel scrolling). The neighbouring "Scroll in the JetBrains IDE terminal" section already shows the pattern of calling out a specific terminal combination, which is exactly what is missing for the WSL2 + Windows Terminal + VS Code case.

Current Documentation

From https://code.claude.com/docs/en/fullscreen, the current "Mouse wheel scrolling" section says:

### Mouse wheel scrolling Mouse wheel scrolling requires your terminal to forward mouse events to Claude Code. Most terminals do this whenever an application requests it. iTerm2 makes it a per-profile setting: if the wheel does nothing but PgUp and PgDn work, open Settings → Profiles → Terminal and turn on Enable mouse reporting. The same setting is also required for click-to-expand and text selection to work. If mouse wheel scrolling feels slow, your terminal may be sending one scroll event per physical notch with no multiplier. Some terminals, like Ghostty and iTerm2 with faster scrolling enabled, already amplify wheel events. Others, including the VS Code integrated terminal, send exactly one event per notch. Claude Code cannot detect which. Set CLAUDE_CODE_SCROLL_SPEED to multiply the base scroll distance... To adjust scroll speed interactively, run /scroll-speed... Separately from the base speed, Claude Code accelerates the scroll rate when you spin the wheel quickly, so a fast spin covers more distance than the same number of slow notches. {/ min-version: 2.1.174 /}To turn acceleration off and keep a constant rate per notch, set wheelScrollAccelerationEnabled to false in settings.json. This setting requires Claude Code v2.1.174 or later.

The section names two specific terminal cases — iTerm2 (per-profile "Enable mouse reporting") and the VS Code integrated terminal (one event per notch) — but does not call out WSL2, Windows Terminal, or the v2.1.172 regression at all. The "terminal" list in https://code.claude.com/docs/en/terminal-config likewise lists Windows Terminal in the "Works without setup" row for Shift+Enter but says nothing about mouse-wheel scroll behavior on WSL2.

The changelog entry for v2.1.179 reads:

Fixed mouse-wheel scrolling in WSL2 under Windows Terminal and VS Code (regression in 2.1.172)

The matching v2.1.172 entry in the same changelog is:

Disable mouse tracking on Windows consoles that don't fully support it

There is no corresponding note in any user-facing doc explaining what to do, or what not to do, if a user on WSL2 hits this before upgrading to v2.1.179, and no note that the behavior changed for the worse in v2.1.172 and is now restored.

What's Wrong or Missing?

A. The WSL2 + Windows Terminal + VS Code combination is not mentioned anywhere in the "Mouse wheel scrolling" guidance

The "Mouse wheel scrolling" section in fullscreen.md enumerates individual terminals (iTerm2, Ghostty, the VS Code integrated terminal) but never groups the WSL2-under-Windows-Terminal-and-VS-Code configuration that v2.1.179 specifically fixes. A user on WSL2 with Windows Terminal hosting VS Code has no doc page to land on that tells them this combination is supported, what to expect, or how to tune it. They will read "Others, including the VS Code integrated terminal, send exactly one event per notch" and either leave with a misleading impression that the documented CLAUDE_CODE_SCROLL_SPEED knob is the fix, or assume mouse-wheel scroll simply does not work in their setup.

B. The v2.1.172 → v2.1.179 regression is undocumented

A user who updated to 2.1.172 and saw their WSL2 mouse-wheel scroll break has no way to discover from the docs that this was a known regression. The two closest things in the changelog — v2.1.172's "Disable mouse tracking on Windows consoles that don't fully support it" and v2.1.179's "Fixed mouse-wheel scrolling in WSL2 under Windows Terminal and VS Code (regression in 2.1.172)" — are not summarized in the troubleshooting page (https://code.claude.com/docs/en/troubleshoot-install) or in the fullscreen.md mouse-wheel section. The troubleshooting page does have WSL1 (Exec format error), WSL npm install, and WSL2 OAuth login subsections, but no WSL2 mouse-wheel/scroll subsection, so a user searching "wsl2 scroll not working" or "wsl2 mouse wheel" has no entry point.

C. The terminal-config.md "Works without setup" row for Windows Terminal does not mention mouse-wheel scroll

https://code.claude.com/docs/en/terminal-config lists Windows Terminal in the Shift+Enter "Works without setup" row without any caveat about mouse-wheel scroll behavior. After the v2.1.179 fix, this is the configuration most users will run, and the doc should say so explicitly so that users on the supported combination are not pushed toward CLAUDE_CODE_SCROLL_SPEED workarounds that they do not need.

Suggested Improvement

Add a new subsection directly under "Mouse wheel scrolling" in https://code.claude.com/docs/en/fullscreen, modeled on the existing "Scroll in the JetBrains IDE terminal" subsection:

### Mouse wheel scrolling in WSL2 On WSL2, the Windows Terminal host and the VS Code integrated terminal running against the WSL2 distribution both forward mouse-wheel scroll events to Claude Code. {/ min-version: 2.1.179 /}Mouse-wheel scrolling in this combination regressed in v2.1.172 and was fixed in v2.1.179; if you are on an older release, upgrade with claude update or set CLAUDE_CODE_SCROLL_SPEED to a value between 1 and 20 as a workaround. No /terminal-setup change or terminal.integrated.mouseWheelScrollSensitivity edit is required on the host side.

Also add a one-line note to the "Enter multiline prompts" Windows Terminal row in https://code.claude.com/docs/en/terminal-config, or to the "Works without setup" sentence that introduces it, indicating that mouse-wheel scrolling is supported in the same configuration. Finally, add a "Mouse wheel scroll does not work in WSL2 on Windows Terminal or VS Code" row to the troubleshooting-symptoms table in https://code.claude.com/docs/en/troubleshoot-install, with the body "Fixed in v2.1.179; upgrade with claude update."

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/fullscreen | "Mouse wheel scrolling" subsection names iTerm2 and the VS Code integrated terminal but never mentions WSL2, Windows Terminal, the v2.1.172 regression, or the v2.1.179 fix |
| https://code.claude.com/docs/en/terminal-config | Shift+Enter "Works without setup" row lists Windows Terminal without mentioning mouse-wheel scroll behavior on WSL2; /terminal-setup description for VS Code mentions terminal.integrated.mouseWheelScrollSensitivity but not the WSL2 case |
| https://code.claude.com/docs/en/troubleshoot-install | Has WSL1 Exec format error, WSL npm install, and WSL2 OAuth login subsections but no WSL2 mouse-wheel/scroll subsection, so a user with a broken WSL2 mouse wheel has no troubleshooting entry point |

Total scope: 3 pages affected.

Version context: The regression was introduced in v2.1.172 and fixed in v2.1.179. The changelog entry for v2.1.172 ("Disable mouse tracking on Windows consoles that don't fully support it") and v2.1.179 ("Fixed mouse-wheel scrolling in WSL2 under Windows Terminal and VS Code (regression in 2.1.172)") are the only places the regression is mentioned anywhere in the docs mirror.