DRAFT — DO NOT FILE WITHOUT V>>'s APPROVAL

Target repo (when V>> approves): anthropics/claude-code Filing checklist: confirm CC version + Ghostty version on the day of filing; re-test reproduction once more on a clean session.

Title

[bug] TUI alt-screen + pinned tasks panel decouples from terminal scrollback on macOS Ghostty

Environment

• Claude Code: 2.1.x (exact build to be filled at filing time via claude --version)
• Terminal: Ghostty 1.3.1 stable (channel: stable)
• OS: macOS 25.3.0 (Darwin)
• Shell: zsh

Reproduction steps

1. Open a Claude Code session in Ghostty: claude --dangerously-skip-permissions (or normal invocation).
2. Generate enough output that the new pinned tasks panel at the top of the viewport is sticky — i.e. multiple tool calls, a long agent run, several screens of output.
3. Mouse-wheel scroll up to view earlier output.
4. Wait for new output to arrive (e.g. another tool call's result streaming in).
5. Observe the tasks panel state.

Expected

• The tasks panel stays pinned and updates live regardless of where the viewport is scrolled.
• The "Jump to bottom (ctrl+End)" affordance reliably returns the viewport to the live region.
• Wheel-scrolling does not detach CC's UI from its own update stream.

Actual

• The tasks panel and the live output region decouple: the panel's stick zone and the scrolled-up viewport render on top of each other, producing visually corrupt frames (truncated lines, ghost characters, half-redrawn panel borders).
• Ctrl+End is the documented "jump to live" key but on macOS Ghostty the natural one-handed gesture is Cmd+Down — there is no built-in CC binding for it, so users press it and nothing happens, compounding the perceived jam.
• Once corrupted, the only reliable recovery is Cmd+K (clear screen) + a Ghostty resize to force a TUI repaint, or killing the claude PID and resuming via claude --continue.

Suggested fix (one of)

1. Use a true alt-screen mode for the TUI. When CC enters its TUI surface, switch to the alt-screen (\x1b[?1049h), which by terminal contract suppresses scrollback entirely. Wheel-scroll then routes to CC's own UI rather than the host terminal's scrollback buffer. On exit, alt-screen restore returns the user to their prior shell output cleanly.
2. Drop the pinned tasks panel — render it inline. The pinned panel is the structural cause: it requires the terminal to render two independent regions (sticky header + scrollable body) while the terminal model assumes one continuous stream. Inline rendering (panel re-emitted at the bottom of each batch of output) sidesteps the decoupling entirely at the cost of more terminal churn.
3. Add a macOS-native Cmd+Down binding alongside the existing Ctrl+End so the recovery affordance is reachable one-handed on Mac keyboards.

Workaround (current users, no upstream change required)

Add to ~/.config/ghostty/config:

keybind = cmd+down=text:\x1b[1;5F
keybind = cmd+up=text:\x1b[1;5H
mouse-shift-capture = false

The first two map Cmd+Down/Cmd+Up to Ctrl+End/Ctrl+Home so CC's existing affordances become reachable one-handed; the third passes wheel events through to the alt-screen consumer so CC's own UI handles them. Validated on Ghostty 1.3.1.

Related visual evidence

(Attach images #11 and #12 from V>>'s /ultraplan session before filing — they show the corrupt-frame state and the affordance-not-triggering state respectively.)