Feature request: alternate screen buffer support in pi-tui

[0xFlo]

Problem

When running pi-tui inside tmux, scrolling up in tmux copy-mode reveals garbled TUI frames stacked in the scrollback buffer. This happens even on brand new tmux sessions with no prior scrollback — the TUI's own startup renders are the only content in the scrollback, and they appear duplicated/garbled when scrolling up.

The issue is most visible at session startup (initial header, auth status, and model info frames appear stacked), but since all rendering goes to the main screen buffer, any TUI frame can end up in tmux's scrollback.

Root cause

pi-tui renders directly on the main screen buffer rather than switching to the terminal's alternate screen buffer. This means every frame pi-tui renders gets captured into tmux's scrollback history.

Most full-screen TUI applications (vim, htop, less, etc.) use the alternate screen buffer via \x1b[?1049h (smcup) on start and \x1b[?1049l (rmcup) on exit. This keeps TUI rendering completely separate from the scrollback and cleanly restores the previous terminal content when the app exits.

Current behavior

• pi-tui uses \x1b[2J\x1b[H (clear screen + home cursor) and synchronized output (CSI 2026) for rendering
• All output goes to the main screen buffer
• pi-tui also emits \x1b[3J (scrollback clear) during full re-renders triggered by width changes
• tmux captures these frames into scrollback
• Scrolling up in tmux shows stacked/garbled snapshots of the TUI, even on a fresh session with zero prior history

Prior art

On this repo

• PR tui: avoid scrollback clear; add followOutput + manual viewport scroll #1232 by @ElliotBadinger — attempted to fix the related \x1b[3J scrollback clear and add viewport scroll controls. Auto-closed by contributor gate. Includes repro evidence confirming pi-tui emits \x1b[3J during full re-renders.
• PR Add regression test for viewport cursor overwrite bug #962 — addressed a related viewport cursor overwrite bug (GH954), fixed in commit a6f9c3c.

Same problem in other AI TUI tools

Tool	Approach	Result
Pi (pi-tui)	No alternate screen	Scrollback pollution in tmux
Claude Code	No alternate screen	Same issues — #2479, #9935, #16310
OpenAI Codex	Uses alternate screen	Opposite problem — can't scroll back in tmux/zellij to review history (#2836)

Suggested fix

Add alternate screen buffer support to ProcessTerminal:

• Send \x1b[?1049h during start() to switch to the alternate screen
• Send \x1b[?1049l during stop() to restore the normal screen

This would solve both problems:

1. During use: TUI frames stay out of tmux scrollback entirely
2. On exit: Previous terminal content is cleanly restored

This could be behind a flag (e.g., useAlternateScreen: true or --alt-screen) for users who prefer the current behavior of preserving output after exit.

Environment

• pi-tui v0.55.1
• tmux 3.5
• Terminal: Alacritty + Ghostty
• OS: Arch Linux (Hyprland/Wayland)

[0xFlo]

One concern with the alternate screen approach: it wipes all conversation history on exit, which kind of defeats the purpose of a terminal-based tool.

A hybrid approach would be ideal — use the alternate screen while running (keeping tmux scrollback clean), but dump the conversation log back to the main screen buffer on exit, similar to how less -X preserves its content after closing.

That way you get the best of both worlds:

1. No garbled frames in tmux scrollback during use
2. Full conversation history preserved in the terminal after exit

This is a problem none of the AI TUIs have solved well yet — could be a real differentiator for pi-tui.