bug: scrollback causes disorienting jumps with duplicate content

[davidpoblador]

Reported by

@blixt

Description

When scrolling up a few lines (e.g., 5 lines to read a paragraph), new output arrives and the user must scroll down past hundreds of lines of duplicate screen content to get back to the bottom. The ratio is severely disproportionate: scroll up 5 lines, scroll down 300+ lines.

This makes scrollback essentially unusable for quick reference during active terminal sessions.

Steps to reproduce

1. Have a workstream with Claude Code actively working (tmux mode)
2. Scroll up ~5 lines to read recent output
3. Wait for Claude to produce new output (TUI redraws)
4. Try to scroll back to the bottom
5. Observe: must scroll past large amounts of duplicate content

Root cause

The issue is a chain of architectural decisions:

1. Alternate screen is disabled

TmuxSession.swift (lines 20-39) configures tmux with:

set -g alternate-screen off
set -ga terminal-overrides ',*:smcup@:rmcup@'

• alternate-screen off disables alternate screen at the tmux pane level
• smcup@ / rmcup@ strips the enter/exit alternate screen escape sequences for all terminal types
• This was intentionally added in commit a455855 ("fix: restore native mouse behavior in tmux terminals") so Ghostty handles mouse events directly

2. Claude Code's TUI redraws the entire screen

Claude Code uses a full-screen TUI that redraws on every update. Normally, TUI apps use the alternate screen buffer, which isolates redraws from scrollback. With alternate screen disabled, every redraw dumps ~50-80 lines (full terminal height) into the normal scrollback buffer.

3. The interaction

1. User scrolls up 5 lines in scrollback
2. Claude produces output, triggering a TUI redraw
3. The redraw writes the entire screen (~80 lines) into the scrollback buffer
4. Multiple rapid redraws compound this (Claude updates frequently)
5. Result: 300+ lines of duplicate content between the user's scroll position and the bottom

Scope

• Tmux mode: Directly affected (alternate screen explicitly disabled)
• Non-tmux mode: Likely unaffected (Ghostty manages alternate screen normally)
• Controlled by @AppStorage("factoryfloor.tmuxMode") in TerminalContainerView.swift

Possible approaches

1. Re-enable alternate screen but find another way to handle mouse passthrough. The original commit suggests this was a tradeoff for native mouse behavior.
2. Use tmux's terminal-overrides more selectively to only strip capabilities that conflict with mouse handling, not smcup/rmcup entirely.
3. Auto-scroll to bottom on new output when the user is within N lines of the bottom (doesn't fix the duplication, but mitigates the symptom).

References

• Sources/Models/TmuxSession.swift lines 20-39 (tmux config)
• Tests/TmuxSessionTests.swift lines 13-19 (testConfigDisablesPaneAlternateScreen)
• Commit a455855 ("fix: restore native mouse behavior in tmux terminals")
• Sources/Views/TerminalContainerView.swift lines 226-237 (tmux mode toggle)

[davidpoblador]

@blixt heads up on this one: the root cause is a deliberate tradeoff. Commit a455855 disabled alternate screen to fix native mouse behavior in tmux terminals. The side effect is that Claude Code's TUI redraws (which happen constantly) dump full-screen content into the scrollback buffer instead of staying in the alternate screen. The fix isn't straightforward since re-enabling alternate screen would regress mouse handling. Might need a more targeted approach to the terminal-overrides.

[blixt]

Interesting! I use iTerm 2 in tmux mode constantly and I don't encounter the same issues with mouse scroll or Claude dumping content into the scrollback buffer... But maybe they do some magic.

I would say if I have to choose one or the other, I'd choose the scrollback working since it's important information and right now it's quite disorienting. And maybe there can be other ways to adjust the scroll speed for those of us who feel it's very slow.

[davidpoblador]

Dug deeper into this with @blixt's preference in mind (scrollback > native mouse scroll). Here's where I've landed.

What the two tmux lines actually do — they're not the same knob:

• `set -g alternate-screen off` — prevents tmux from entering the outer terminal's alternate screen. This is what causes Ghostty to send trackpad scroll events as native scrollback instead of converting them to arrow keys. Per Ghostty's `Surface.zig:3479`, the scroll→arrows conversion only happens when the active screen IS the alternate screen, no explicit mouse reporting is active, and alt-scroll mode is set. So this line is the mouse-scroll fix.
• `set -ga terminal-overrides ',*:smcup@:rmcup@'` — strips the alt-screen enter/exit capability from the terminfo that inner programs inside tmux panes see. This prevents Claude Code's TUI from entering a nested alt-screen. It doesn't affect mouse scrolling at all.

So dropping `smcup@:rmcup@` alone would not restore scrollback — the pollution comes from `alternate-screen off`. The real choice is binary: alt-screen off → mouse works but scrollback fills with redraw dumps; alt-screen on → scrollback stays clean but Ghostty converts trackpad scroll to arrow keys (you'd scroll inside the TUI instead of the buffer).

Why iTerm2 is different: iTerm2 has a "Save lines to scrollback in alternate screen mode" toggle and aggressively dedups redraws. Ghostty faithfully emits every byte — the right behavior for a terminal emulator, but without iTerm2's extensions we can't get both at once on Ghostty.

Plan: honor @blixt's preference and revert both tmux settings. Accept the mouse-scroll regression (users can use Shift+scroll or keyboard for navigation inside TUIs). Update the two tests in `Tests/TmuxSessionTests.swift:13,17` — they'd need to be deleted, not flipped, since the behavior they assert is no longer a feature.

Optional mitigation for users who want alt-screen back: `scroll-to-bottom = output` in `~/.config/ghostty/config` auto-scrolls on new output, which hides most of the pollution symptom. Not a fix, but worth documenting.

I'll pick this up with a PR shortly. Keeping the issue open as the tracker.