claude-code - 💡(How to fix) Fix [BUG] CLAUDE_CODE_DISABLE_MOUSE=1 + terminal scroll wheel = only full-page scroll; no line-granularity option exists

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When CLAUDE_CODE_DISABLE_MOUSE=1 is set, Claude Code does not emit terminal mouse reporting escape sequences. The terminal emulator (Alacritty, and likely all others) therefore handles scroll wheel events itself. In alt-screen mode — which Claude Code uses — Alacritty's default behaviour is to convert wheel events into Page Up (\x1b[5~) / Page Down (\x1b[6~) key presses and send them to the application. Claude Code responds to those keys by scrolling exactly one full viewport at a time.

Attempting to remap wheel events to Up/Down arrow keys (\x1b[A / \x1b[B) in Alacritty's config makes things worse: Claude Code's input field intercepts arrow keys as command-history navigation rather than viewport scrolling, so the wheel ends up cycling through previous prompts instead of scrolling the conversation.

The result is a hard fork with no middle ground:

┌──────────────────────────────────────┬─────────────────────────┬─────────────────────┐ │ Configuration │ Scroll behaviour │ Text selection │ ├──────────────────────────────────────┼─────────────────────────┼─────────────────────┤ │ Mouse enabled (no DISABLE_MOUSE) │ Smooth (~3 lines/tick) │ Requires Shift+drag │ ├──────────────────────────────────────┼─────────────────────────┼─────────────────────┤ │ DISABLE_MOUSE=1 + wheel→Page Up/Down │ Full page per tick │ Normal drag │ ├──────────────────────────────────────┼─────────────────────────┼─────────────────────┤ │ DISABLE_MOUSE=1 + wheel→arrow keys │ Navigates input history │ Normal drag │ └──────────────────────────────────────┴─────────────────────────┴─────────────────────┘

Note: issues #46615 and #12953 cover related scroll symptoms but were closed as duplicates pointing to issues that don't match this specific scenario (the DISABLE_MOUSE interaction). This is a distinct issue about the lack of any granular scroll option in the mouse-disabled code path.

What Should Happen?

Expected behavior: Mouse scroll wheel should scroll the conversation viewport smoothly (a few lines per tick), and left-click drag should copy selected text to the primary selection buffer — simultaneously, without either feature requiring the other to be disabled.

Error Messages/Logs

Steps to Reproduce

One of the following would resolve this:

1. A scroll-lines-per-page config option that applies to Page Up/Down handling inside Claude Code (e.g. CLAUDE_CODE_SCROLL_LINES=5). Currently CLAUDE_CODE_SCROLL_SPEED appears to only affect mouse-driven scroll when mouse is enabled.
2. A dedicated viewport-scroll key binding (e.g. Ctrl+Up/Ctrl+Down, or Shift+Up/Shift+Down) that Claude Code listens for and scrolls the viewport by N lines, distinct from arrow-key history navigation. Users could then map their wheel to that sequence in their terminal config.
3. A way for DISABLE_MOUSE=1 to coexist with smooth scroll — for example, by having Claude Code read scroll wheel events via a separate mechanism that doesn't interfere with the terminal's own text selection.

Steps to reproduce

1. Set CLAUDE_CODE_DISABLE_MOUSE=1 in your environment.
2. Run claude in any terminal emulator (reproduced in Alacritty 0.17.0).
3. Generate a response long enough to scroll.
4. Use the mouse scroll wheel.

Expected: viewport scrolls a few lines per tick Actual: viewport jumps one full page per tick

Additional context

CLAUDE_CODE_DISABLE_MOUSE=1 is the documented workaround for the text-selection regression introduced in v2.1.148 (mouse reporting broke plain drag-to-select on Linux). Fixing scroll for users who rely on this flag would restore reasonable usability without requiring them to give up native text selection.

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

Unknown — the issue has existed since at least v2.1.88

Claude Code Version

2.1.150

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

Which terminal are you using? Alacritty 0.17.0

The core issue is not the mouse interaction change itself, but the absence of a user-configurable option to revert to the previous behavior. Please provide a mechanism — whether an environment variable, a config setting, or a CLI flag — that allows users to opt out of the new mouse handling and restore the pre-v2.1.88 interaction model.