Terminal randomly scrolls to top and auto-scrolls to bottom during output, breaking scrollback navigation

Open 💬 18 comments Opened Mar 16, 2026 by r4d10n

Problem

Two related scrolling issues in the Claude Code terminal:

1. Viewport jumps to the TOP randomly, even when idle

The terminal spontaneously scrolls to the very top of the scrollback history, even when Claude is not generating output. This happens unpredictably and forces the user to scroll all the way back down to where they were reading.

2. Auto-scroll during output generation overrides manual scrolling

When Claude is actively generating output (streaming tokens or running tools), the terminal automatically scrolls to follow the latest output. This overrides any manual scrolling the user is doing.

Steps to Reproduce

Random scroll-to-top (Issue 1):

Have a conversation with substantial history
Scroll up to read previous output (while Claude is idle / not generating)
The viewport randomly jumps to the very top of the history

Auto-scroll override (Issue 2):

Start a conversation that produces long output
While output is still streaming, try to scroll up to read earlier content
The viewport snaps back to the bottom as new content renders

Expected Behavior

The viewport should never jump to the top on its own
Users should be able to scroll freely through history without the position being reset
Auto-scroll should pause when the user manually scrolls away from the bottom, and resume only when the user scrolls back to the bottom

Impact

This is a significant usability pain point. The random scroll-to-top is especially disruptive — it makes reading through conversation history unreliable and frustrating. Users lose their place constantly.

Environment

Platform: Linux (Manjaro)
Terminal: standard terminal emulator
Claude Code: latest version

18 Comments

github-actions[bot] · 4 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

yurukusa · 4 months ago

Both issues are related to how Claude Code manages the terminal viewport via ANSI escape sequences (specifically CSI sequences for cursor positioning).

Issue 1 (random scroll-to-top): This typically happens when Claude Code emits a "save cursor position" (\e[s) without a matching restore, or when the status line refresh triggers a full-screen redraw via \e[H (cursor home). The idle-state UI refresh cycle can cause this even when no output is being generated.

Issue 2 (auto-scroll override): Claude Code uses \e[?25l (hide cursor) + write + \e[?25h (show cursor) patterns during streaming. Each write cycle implicitly moves the viewport to the cursor position, which is always at the bottom.

Workaround for tmux users:

# In .tmux.conf — force alternate screen buffer
set -g alternate-screen on

# This isolates Claude Code's cursor manipulation from your scrollback
# You can then use tmux's own scroll mode (prefix + [) freely

Workaround for terminal multiplexer users (screen/tmux):

The most reliable fix is to run Claude Code inside tmux or screen, which gives you a separate scrollback buffer that Claude Code's escape sequences cannot touch. You scroll the outer buffer, not the inner one.

For native terminal users:

Some terminals support "scroll lock" when you manually scroll up:

Windows Terminal: Settings → Profiles → Advanced → "Automatically scroll to bottom on output" = OFF
kitty: scrollback_pager_history_size + scrollback_fill_enlarged_window no

Check your terminal's documentation for an equivalent "don't chase new output while scrolled up" setting.

These settings prevent the terminal from chasing new output when you are reading history.

kjyv · 4 months ago

iTerm2: Enable "Scroll to bottom on output" = OFF in Preferences → Profiles → Terminal

This doesn't seem to exist. Is this a claude generated answer or what?

yurukusa · 4 months ago

Apologies — my iTerm2 setting suggestions were wrong in both attempts. I don't use iTerm2 and was guessing incorrectly. The tmux workaround in my first comment should still work though.

factorshin · 4 months ago

You're right, that iTerm2 setting doesn't exist — I mixed it up with a similar setting in other terminals. Apologies for the bad info. The tmux workaround above should still work for iTerm2 users. For native iTerm2 scrollback, the relevant setting is actually under Preferences → Profiles → Terminal → "Scroll to bottom on key press" (which is on by default), but there's no direct "scroll to bottom on output" toggle like in Windows Terminal or GNOME Terminal.

In my iTerm2(version: 3.6.9), I can't find the 'Scroll to bottom on key press' option under Preferences → Profiles → Terminal. Is it removed or moved somewhere else?

kjyv · 4 months ago

You're right, that iTerm2 setting doesn't exist — I mixed it up with a similar setting in other terminals. Apologies for the bad info. The tmux workaround above should still work for iTerm2 users. For native iTerm2 scrollback, the relevant setting is actually under Preferences → Profiles → Terminal → "Scroll to bottom on key press" (which is on by default), but there's no direct "scroll to bottom on output" toggle like in Windows Terminal or GNOME Terminal.

Please stop trying to give advice if you have no idea and just use Claude Code to generate answers. We can all do that ourselves if we think that helps - hint: it does not

nullbio · 3 months ago

Still broken as of v2.1.81:

felipekj · 3 months ago

+1 — experiencing this on GNOME Terminal (same behavior as IntelliJ terminal). Cursor randomly scrolls up during streaming output.

tonylin75 · 3 months ago

It was fine when I used iterm + claude code. but when I used tmux with claude code the scroll jump goes crazy.. can't find a way to fix it yet.

andreas-civic · 3 months ago

I can reproduce this consistently. One additional observation:

When staying at the bottom of the output, it works fine — the view correctly follows new output. The issue only occurs when you scroll up to read previous output. As soon as Claude writes a new line, the view jumps to the top of the conversation instead of staying at the scrolled position.

This happens in VS Code's integrated terminal on macOS. I confirmed it's Claude Code-specific — running a regular command with continuous output in the same VS Code terminal lets you scroll up and stay in place while output continues below.

So the bug seems to be in Claude Code's terminal renderer: when new content is appended and the viewport is not at the bottom, it re-anchors to the top instead of maintaining the current scroll position.

jpsear · 3 months ago

Am also getting this frustrating bug.

--version: 2.1.81 (Claude Code)

Running in iTerm 2 on Mac 26.3.1

sstraus · 3 months ago

👍 We're experiencing the same issue embedding xterm.js 6.0.0 in a Tauri app. The scroll position jumps when Claude Code redraws its TUI while the user is scrolled up. Confirmed root cause: cursor-up sequences exceeding viewport height + ESC[2J/ESC[3J.

belousoves · 3 months ago

Have the same issue with Gnome terrminal 3.44.0. Extremely annoying and prevent you to reading anything while claude still work.

copperx · 3 months ago

Any updates or workarounds?

YossiSaadi · 3 months ago

PLEASE 😢

alisonjf · 3 months ago

Dude that's frustrating, feel like "read previous output FAST GOGO YOU HAVE 3 SECONDS"

jgwill · 3 months ago

I confirmed it's Claude Code-specific

On my part, I have the same experience with claude-code but also with other harness such as pi-mono. I am questionning, which logics do they have in common ? 'Checking width or height of the terminal for the TUI refresh ? Something else ?

parsakhaz · 3 months ago

this is a huge issue. love claude code but this makes it really really hard to use

hey. it's fixed at the terminal level here

https://github.com/Dcouple-Inc/Pane/pull/120

open source, using xtermjs which is the same terminal as VS Code. feel free to copy this fix or download the latest release to run claude code on any operating system with the fix in place. i was so mad and frustrated at this that I had to fix it myself.

Not just a scrolling issue — also a rendering/layout problem in VS Code's side-by-side panel mode. When Claude Code runs in VS Code with the terminal on one side and the editor on the other, text formatting breaks in unpredictable ways. Options and multi-line output get weirdly split left-right, text wraps incorrectly, and the whole experience feels janky rather than fluid. Combined with the scroll-jumping, longer sessions in VS Code become genuinely hard to follow. This isn't just macOS standalone terminal — it's very much a VS Code integrated terminal issue too.

yeah i had to switch off cursor/vscode and build myself an ide that managed xtermjs (the library they both use) well enough for the complex TUIs to not break.

works great and i have a fix for the scroll jump i just implemented rn here