Pi Scroll

pi-scroll is a Pi package that adds /scroll: a fast, keyboard-driven search dialog for your Pi session history.

It searches Pi's JSONL session files on demand with ripgrep, shows readable chat-oriented results, renders a rich transcript preview, and switches Pi to the selected session when you press Enter.

Preview

The package gallery image is configured in package.json as pi.image and uses this screenshot when the package is published.

Why this exists

Pi sessions accumulate quickly. Once you have more than a handful of projects and branches, remembering the exact session you want to resume becomes painful.

pi-scroll is meant to feel like a small Telescope/fuzzy-finder style picker for Pi history:

1. Run /scroll inside Pi.
2. Type a phrase you remember from a previous conversation.
3. Search the current project history by default, or toggle all global history.
4. Inspect the session preview without leaving the dialog.
5. Press Enter to switch to the selected session.

No persistent index is created. Search happens live against Pi's existing session files.

Features

• Adds the /scroll command.
• Searches Pi JSONL session history with rg/ripgrep.
• Defaults to current-project history, with a global-history toggle.
• Filters out noisy tool calls/results by default with an optional all mode.
• Supports fixed-string search by default and regex search on demand.
• Shows one best match per session, ranked toward human-readable chat entries.
• Displays session title / first user prompt, cwd metadata, role, line number, and match snippet.
• Skips the currently active session so results focus on sessions you can switch to.
• Shows a rich session preview pane when terminal width allows it.
• Renders previews with Pi-style user, assistant, branch summary, compaction, and tool-result components.
• Loads long previews incrementally and fetches more content as you scroll.
• Supports preview focus and scrolling for longer previews.
• Has built-in help (Ctrl+H) with all shortcuts.
• Loads user and project config from pi-scroll.json files.

Installation

Once published to npm, install with Pi:

pi install npm:pi-scroll

Or try it without installing:

pi -e npm:pi-scroll

For local development/testing from this repository:

pi -e .

You can also point directly at the extension file:

pi -e ./extensions/scroll.ts

Usage

Start Pi with the package enabled, then run:

/scroll

Type a search query. Results appear once the query reaches the configured minimum length, which is 2 characters by default.

Press Enter on a result to switch Pi to that session.

Keyboard shortcuts

Search and filters

Shortcut	Action
Ctrl+G	Toggle current-project (CWD) vs global session history
Ctrl+T	Toggle chat vs all filter mode
Ctrl+R / Ctrl+S	Toggle fixed-string vs regex search
Ctrl+O	Open/close preview
Ctrl+H	Toggle help

Navigation

Shortcut	Action
Up / Down	Move through results; scroll preview when preview is focused
Ctrl+P / Ctrl+N	Move through results; scroll preview when preview is focused
Tab	Focus preview; opens it if needed; press again for results
Ctrl+D / Ctrl+U	Scroll preview down/up by half a page whenever preview is open
Enter	Switch to selected session
Esc	Close help or cancel /scroll

Query editing

Shortcut	Action
Ctrl+A	Move to start of query
Ctrl+E	Move to end of query
Ctrl+B / Ctrl+F	Move left/right
Alt+B / Alt+F	Move by word
Ctrl+V / Ctrl+W	Delete word backward
Alt+D	Delete word forward
Ctrl+D	Delete character under cursor when preview is closed
Ctrl+U / Ctrl+K	Delete to start/end when preview is closed

Preview behavior

The preview is a best-effort transcript view of the selected session. It uses Pi's own rendering components where possible, so messages look closer to the normal transcript than a raw JSON dump.

Preview supports:

• user and assistant messages
• visible assistant thinking/text
• branch summaries and compactions
• compact tool-result cards
• richer tool execution rendering when Pi's TUI context is available
• lazy loading for long or growing session files

For narrow terminals, the preview does not render side-by-side. Press Tab to focus the preview as a full-width pane, or Ctrl+O to toggle it.

Search modes

pi-scroll has two scope modes:

• cwd: search sessions for the current working directory/project.
• global: search all Pi sessions under the agent session directory.

It also has two filter modes:

• chat: default; searches user messages, assistant text, session names, labels, branch summaries, and compactions while avoiding noisy tool calls/results.
• all: includes tool-heavy entries too.

And two search modes:

• fixed: default; safe literal matching through ripgrep fixed-string search.
• regex: ripgrep regex search.

Configuration

Defaults live in src/config.ts.

User overrides are loaded from:

~/.pi/agent/pi-scroll.json

Project overrides are loaded from:

.pi/pi-scroll.json

Project config wins over user config.

Example:

{
  "preview": true,
  "defaultScope": "cwd",
  "defaultFilterMode": "chat",
  "defaultSearchMode": "fixed",
  "maxResults": 50
}

Options

Option	Default	Description
preview	true	Whether the preview pane starts open.
previewMinWidth	100	Minimum terminal width required for side-by-side preview.
previewRatio	0.58	Fraction of side-by-side width allocated to the preview pane.
heightRatio	0.8	Fraction of terminal height used by the overlay.
maxPreviewMessages	18	Number of preview entries loaded per lazy-loading batch.
maxPreviewCharsPerMessage	260	Base truncation size used for long user-message preview text.
defaultScope	"cwd"	Initial scope: "cwd" or "global".
defaultFilterMode	"chat"	Initial filter: "chat" or "all".
defaultSearchMode	"fixed"	Initial search mode: "fixed" or "regex".
minQueryLength	2	Minimum query length before search starts.
maxResults	50	Maximum result count.
maxResultTextLength	500	Maximum text extracted for each result snippet.
ripgrepMaxCount	10	Maximum ripgrep matches per file before TypeScript-side scoring.
navigationWrapQuietMs	180	Delay used to avoid accidental wraparound while holding navigation keys.

Runtime requirement

rg/ripgrep must be available in PATH.

On macOS:

brew install ripgrep

Package structure

The package is exposed to Pi through the pi manifest in package.json:

{
  "name": "pi-scroll",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "image": "https://unpkg.com/pi-scroll@0.1.0/assets/screenshot.png"
  }
}

The extension entry point is extensions/scroll.ts. The command registered with Pi remains /scroll.

Development

This repo uses Vite+ via vp:

vp install
vp check
vp test