macOS/iTerm2: scroll wheel scrolls the terminal instead of the CLI transcript, making earlier conversation unreachable

[lizhiqiangcs]

Describe the bug

On macOS with iTerm2, scrolling with the mouse wheel (or a two-finger trackpad scroll) inside a Copilot CLI session does not scroll the CLI's own conversation view. The scroll is handled by the terminal instead, which scrolls its scrollback buffer.

Because the CLI renders in the alternate screen buffer, that buffer only ever contains fragments of the TUI's in-place repaints. Scrolling up therefore shows duplicated and interleaved lines rather than earlier conversation — every line appears twice, offset by a few columns. The practical effect is that only the last screenful of a session is readable and there is no way to scroll back to earlier assistant output.

Affected version

1.0.75 (@github/copilot)

Steps to reproduce the behavior

1. Run copilot in iTerm2 on macOS.
2. Have a conversation long enough that the output exceeds the window height.
3. Scroll up with the mouse wheel or a two-finger trackpad scroll.
4. The terminal's scrollback scrolls rather than the CLI transcript, the rendered content is duplicated and misaligned, and earlier conversation cannot be reached.

Expected behavior

Scrolling with the wheel inside the CLI should scroll the CLI's own conversation transcript, as alternate-screen TUIs that implement their own viewport do.

Failing that, a documented way to keep the session in the normal scrollback buffer would solve it just as well, so the terminal's native scrollback works as users expect.

Additional context

Environment

Copilot CLI	1.0.75 (@github/copilot)
OS	macOS 26.5.2 (build 25F84)
CPU	arm64 (Apple Silicon)
Terminal	iTerm2 3.6.11
TERM	xterm-256color
TERM_PROGRAM	iTerm.app (3.6.11)
Shell	zsh
Node	v22.22.2

Settings (~/.copilot/settings.json — company-internal plugin, marketplace and MCP entries removed)

{
  "logLevel": "all",
  "model": "claude-opus-5",
  "mouse": false,
  "experimental": false,
  "effortLevel": "max",
  "contextTier": "long_context"
}

3 MCP servers and 2 plugins are configured; both are internal so their names are omitted. I do not believe either is related, as the behavior reproduces regardless of what the session is doing.

What I found while investigating locally

• The CLI enters the alternate screen buffer (ALT_SCREEN_ON: "\x1b[?1049h" in the shipped bundle), which by design has no scrollback of its own.
• iTerm2's Save lines to scrollback in alternate screen mode (Profiles → Terminal, on by default) is what captures the partial repaints, and is the direct cause of the duplicated/interleaved lines. Turning it off stops the garbling, but of course does not make earlier conversation reachable.
• I could not find a way to opt out of the alternate screen in 1.0.75. Grepping the shipped bundle for COPILOT_* environment variables turned up nothing screen-related. Some other agent CLIs expose one for exactly this reason (for example CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN).
• There is a --mouse flag documented as "Enable mouse support in alt screen mode", and my settings have "mouse": false. I searched the bundle for wheel/scroll handling and only found syntax-highlighting keyword lists, so I do not think enabling it would give transcript scrolling. If it is intended to, that is not discoverable from the flag description.
• Ctrl+O ("toggle all timeline"), /search and /share do let me reach the history, so this is a UX and discoverability gap rather than data loss. It is still a surprising break from the scrolling behavior every other terminal program has.

I am happy to attach a screenshot of the garbled scrollback if that is useful — I left it out because the frame contains working content.

[lizhiqiangcs]

Resolved — this was my own misconfiguration, and one incorrect claim in the original report needs correcting.

Setting mouse to true fixes it completely:

/settings set mouse true

The wheel now scrolls the CLI transcript as expected.

Correcting my original report. I wrote that I did not think enabling --mouse would give transcript scrolling, based on grepping the bundle for wheel/scroll handling and finding nothing. That was wrong — I searched for "wheel", but xterm encodes the wheel as mouse buttons 4 and 5, so the relevant code never matched. The CLI does implement transcript scrolling, gated on the mouse setting. My settings.json had "mouse": false, so the handler was never installed and iTerm2 handled the wheel itself, scrolling its own scrollback — which in the alternate screen buffer contains only fragments of the TUI's repaints, hence the duplicated and misaligned lines.

So there is no scrolling bug here. Closing.

Two small things a maintainer may or may not think worth acting on, offered only as feedback:

• The flag description, "Enable mouse support in alt screen mode", does not hint that transcript scrolling is what it gates. Something like "enables mouse support, including scrolling the conversation with the wheel" would have saved me the trip.
• When mouse support is off and the terminal is in the alternate screen buffer, scrolling is guaranteed to produce garbled output rather than history. A one-time hint on the first wheel event in that state could turn a confusing failure into a discoverable setting.

Thanks, and apologies for the noise.