pi-scroll-lock

Freeze the pi TUI screen on demand so the terminal scrollback stops yanking you to the bottom while the agent keeps streaming.

The problem

pi renders the whole chat into the terminal's normal scrollback and keeps writing new lines at the bottom while the agent generates. When you scroll up to read, those writes pull the terminal viewport back down — every token yanks you to the bottom. The pi maintainers closed this as "cannot be done without alt buffer" (earendil-works/pi#4679), which pi deliberately does not use.

This package delivers the same outcome through the extension API instead.

Install

Local path (already installed on this machine):

pi install /path/to/pi-scroll-lock

From git after pushing:

pi install git:github.com/duongvm57/pi-scroll-lock

From npm after publishing:

pi install npm:pi-scroll-lock          # or npm:@<you>/pi-scroll-lock if the name is taken

Or try it once without installing:

pi -e git:github.com/duongvm57/pi-scroll-lock

Usage

| Key | Action | |-----|--------| | Alt+S | Toggle scroll lock |

1. The agent starts streaming and you want to read earlier output.
2. Press Alt+S — the screen freezes. The agent keeps working underneath, but pi writes nothing to the terminal, so your scroll position is safe. Scroll up and read at leisure.
3. Press Alt+S again (or the agent finishes) — the screen is redrawn with the latest state at the bottom.

While locked:

• Esc / Ctrl+C still pass through (interrupt the agent).
• Everything else is swallowed so you can't edit the invisible input.
• The footer shows 🔒 Scroll lock ON — Alt+S to resume.

The lock auto-releases when the agent settles (no retries/compaction/follow-ups pending). Set PI_SCROLL_LOCK_NO_AUTOUNLOCK=1 to keep the screen frozen until you unlock manually.

How it works

• Captures the live TUI instance via a widget factory (called synchronously with the real TUI).
• On lock: wraps tui.requestRender / tui.doRender so no output reaches the terminal. The agent loop and message store are unaffected — only rendering stops.
• A raw-input listener (ctx.ui.onTerminalInput) makes Alt+S work even while frozen and blocks invisible typing.
• On unlock: restores the originals and forces requestRender(true) — a full clear + redraw of the latest state.
• Alt+S is also registered as a proper extension shortcut (listed in the /help hotkeys table).

Limitations

• The frozen screen is a snapshot: status/tool-output updates are not visible until you unlock (same trade-off as tmux copy mode).
• Unlocking redraws at the bottom — the final jump is by design.
• The toggle key is Alt+S (both classic ESC s and kitty keyboard-protocol encodings are matched). Rebinding is not supported yet.
• If a full-screen selector is open when you lock, Alt+S still unlocks (input listeners run before overlays).