Chat TUI auto-scrolls to bottom unconditionally — request followTail toggle / scroll-lock

[aydemir]

Summary

In the chat TUI, new content (assistant stream, bash output, session switch, user submission) unconditionally scrolls the viewport to the bottom. There is no way to read earlier messages by scrolling up — every new token yanks the viewport back down. Other harnesses (OpenCode, Claude Code, Aider) expose a follow-tail toggle / scroll-lock; Mavis Code does not.

Steps to reproduce

1. Install @minimax-ai/code (verified on v0.5.2; upstream source reflects the same behavior in v0.4.12).
2. Launch mcode and start any conversation.
3. Scroll up with PageUp / mouse-wheel to read an earlier message.
4. As soon as the assistant or bash flow emits new content, the viewport is yanked back to the bottom.

Expected

• A user who has scrolled up should remain where they are until they choose to return (e.g. End, click on the bottom indicator, or a followTail: true toggle).
• Behavior parity with at least one other major TUI coding agent.

Actual

• The viewport is reset to the bottom on every content change, regardless of where the user is reading.

Root cause (from source)

followBottom() is unconditional — no isAtBottom() / userScrolled guard.

packages/tui/src/tui/shell/chat-layout.ts:142-144

followBottom(): void {
  this.fullscreenBodyViewport.scrollToEnd();
}

Call sites that auto-trigger this:

• packages/tui/src/tui/app.ts:111-114 — bash flow change
• packages/tui/src/tui/app.ts:128-131 — user submission
• packages/tui/src/tui/controller/session-flow.ts:146 — session reset
• packages/tui/src/tui/controller/session-flow.ts:218 — session switch
• packages/tui/src/tui/app-composition.ts:488 — composition callback

Existing keybinds (for context)

packages/tui/src/tui/engine/keybindings.ts:208-209 already has top/bottom bindings, but they only jump manually — they don't toggle follow-mode.

"tui.altScreen.top":    { defaultKeys: "home", description: "Scroll viewport to top" },
"tui.altScreen.bottom": { defaultKeys: "end",  description: "Scroll viewport to bottom" },

Suggested fix (sketch — non-blocking)

1. Track isFollowing in ChatLayout (true while viewport is at/near bottom, false after the user scrolls up).
2. Guard each call site so followBottom() becomes a no-op when !isFollowing.
3. Expose a config key (e.g. tui.chat.followTail: "auto" | "always" | "off", default "auto") and a status-bar indicator showing current state.
4. End / tui.altScreen.bottom re-arms follow mode.

Happy to send a PR if maintainers agree on the design.

Environment

• Mavis Code: @minimax-ai/code@0.5.2
• Upstream source inspected: MiniMax-AI/minimax-code @ main (v0.4.12 source preview, behavior identical)
• OS: Android (Termux + proot-distro Debian 13) — but the issue reproduces on desktop terminals as well.

Severity

UX, not data-loss. Workaround: increase terminal scrollback buffer on the client side.

[hetaoBackend]

This was generated by AI during triage.

Thanks for the precise report. Verified against current main: followBottom() in packages/tui/src/tui/shell/chat-layout.ts is indeed an unconditional scrollToEnd() with no isAtBottom() / user-scroll guard, and the call sites you list (bash flow change, user submission, session reset/switch, composition callback) all trigger it. So while streaming, scrolling up to read earlier output does get yanked back down — confirmed as a real UX gap rather than a misconfiguration.

Your sketch matches how we'd want this fixed:

1. Track a follow state in ChatLayout — set false once the user scrolls away from the bottom, restore true when they return to the bottom (via End, mouse, or an explicit action).
2. Make the auto-follow call sites no-ops while not following. A user's own submission is a reasonable exception that may re-enable follow.
3. A visible "new output below" indicator while detached would help discoverability.

One design note: session switch/reset probably should keep jumping to the bottom (fresh context), so the guard likely applies to streaming/tool-output updates rather than every call site uniformly.

Triaging as enhancement + tui. A PR along the lines above would be welcome — the existing tui.altScreen.top/bottom keybindings give a natural place to hook the re-follow action.