[Bug] Scroll position resets to top during agent execution

We hit this too and collected working workarounds into a repo: claude-code-scroll-fix

Quick fix (Windows Terminal): Add "snapOnOutput": false to your profiles.defaults in settings.json. Reduces jumping ~60-70%.

Complete fix: Run Claude inside tmux — it completely decouples your scroll position from Claude's cursor repositioning. The repo has a one-click installer that sets up WSL + tmux + a Windows Terminal profile.

Root cause: Claude Code uses CSI escape sequences to rewrite the thinking spinner in-place, and terminals follow the cursor position back up. snapOnOutput only fixes output-triggered scrolling, not cursor repositioning — tmux fixes both.

Confirmed same behavior on Windows Terminal + PowerShell (v2.1.76). Filed #34794 with Windows-specific details. This affects multiple platforms (macOS iTerm, Windows Terminal, WSL2) — likely a core rendering/cursor issue in the CLI output layer.

Root cause traced in cli.js v2.1.76 source: Ink's rendering uses \ on every re-render. When output is large, the cursor moves far up in the buffer and Windows Terminal (and iTerm) follows the cursor, snapping the viewport to the top. Full analysis in #34794.

Updated PR #34798 with v2 fix: stateful stdout.write interceptor that clamps cursor-up across ALL writes (not just sync blocks). Catches Ink renderer, prompt renderer, and all other cursor-up sources. Patch + PowerShell script included.

Updated PR #34798 with 3 combined patches: (1) stateful stdout.write interceptor clamping cursor-up, (2) render throttle 16ms→200ms, (3) disable synchronized update mode. All three are needed — cursor-up clamping alone does not fix it because Windows Terminal exits scroll mode on ANY stdout write, and sync blocks batch writes into one viewport-resetting update. PowerShell apply/revert script included.

v3 update: Previous fixes (cursor-up clamping, disabling sync update) did not work and caused flickering.

Root cause identified: Windows Terminal bug microsoft/terminal#14774 — SetConsoleCursorPosition always scrolls viewport to cursor, even when visible. Every Ink re-render triggers this. Cannot be fixed from within the process.

v3 patch: render throttle SK6=16 → SK6=1000 (1fps). Gives 1 second of uninterrupted reading between viewport resets. Trade-off: streaming text in ~1s chunks. No flickering.

PR #34798 updated. Real fix needs Microsoft (terminal#14774) or Anthropic (PTY proxy/append-only rendering).

v5 update: Fundamentally different approach — buffer ALL Ink renders during active work, screen stays frozen (no viewport jumping). Flush only when (a) user types (at prompt/bottom, safe to update) or (b) 5s of no renders (Claude finished). Previous v1-v4 failed because WT bug microsoft/terminal#14774 triggers viewport scroll on ANY cursor positioning. v5 avoids this by not writing to stdout at all during active work. Trade-off: no spinner/progress visible during work. PR #34798 updated.

v6: Buffer ALL renders, flush ONLY on user input (stdin). No timer. No auto-flush. Zero viewport jumping while not at bottom. Root cause: WT bug microsoft/terminal#14774. PR #34798.

v7: Replay ALL buffered frames on flush (fixes v6 outdated screens). Keeps entire diff chain so screen content is always correct. Still zero viewport jumping — flush only on user input (stdin). PR #34798.

Final fix: Ctrl+6 freeze toggle. Press Ctrl+6 to freeze screen (buffer renders, scroll freely). Press again to unfreeze (replay + live output). Tab title shows [FROZEN]. Root cause is WT bug microsoft/terminal#14774 — cannot be detected/fixed automatically. PR #34798.

try this

### iTerm2 Global Settings
AppleScrollAnimationEnabled = 0
NSScrollAnimationEnabled = False
NSScrollViewShouldScrollUnderTitlebar = False

### iTerm2 tmux Profile (scroll-related)
| Setting | Value |
|---------|-------|
| Scroll To Bottom On Output | False |
| Scrollback Lines | 3000 |
| Scrollback in Alternate Screen | False |
| Scrollback With Status Bar | False |
| Allow Alternate Mouse Scroll | True |
| Mouse Reporting | False |
| Disable Window Resizing | True |

### tmux Config (~/.config/.tmux.conf)
```bash
set -g alternate-screen off # let iTerm2 handle screen switching
# set -ga terminal-overrides ',xterm*:smcup@:rmcup@' # disabled

Still broken as of v2.1.81:

https://github.com/anthropics/claude-code/issues/36582
https://github.com/anthropics/claude-code/issues/35403
https://github.com/anthropics/claude-code/issues/36816
https://github.com/anthropics/claude-code/pull/35683
https://github.com/anthropics/claude-code/issues/33814
https://github.com/anthropics/claude-code/issues/34845
https://github.com/anthropics/claude-code/issues/33367
https://github.com/anthropics/claude-code/issues/34400
https://github.com/anthropics/claude-code/issues/826
https://github.com/anthropics/claude-code/issues/36621
https://github.com/anthropics/claude-code/issues/36128
https://github.com/anthropics/claude-code/issues/35766
https://github.com/anthropics/claude-code/issues/34242
https://github.com/anthropics/claude-code/issues/18299

This is a duplicate of #35403, which was fixed as of version 2.1.101.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.