pi-session-finder

Cross-project session search & jump for pi.

Adds a /find [keywords…] command that full-text searches every past session across all projects, shows the matches with the keyword in context, and on selection switches to that session and its project directory — the same outcome as /resume, but driven by content search instead of a name picker.

Why

pi's built-in /resume picker filters sessions by name / first message only. There is no way to "find the session where I worked on X." This extension searches the full text of every session (via SessionManager.listAll(), which already pre-extracts allMessagesText) and jumps you straight there.

Install

pi install npm:pi-session-finder

Or load it ad-hoc:

pi -e ./src/index.ts

Usage

/find stripe webhook        # AND-match across name, cwd, and full message text
/find "stripe webhook"      # quoted phrase → matched as a single substring
/find BusinessCentral       # matches by project path too
/find                       # opens a search prompt (type to search)
/find-back                  # jump back to the previous session/project

Pick a result with the arrow keys + Enter to switch into that session and its working directory (pi re-runs project trust for the target cwd, just like /resume). Esc / Ctrl+C cancels.

Each result shows the session name (or first message), the project folder, how long ago it was modified, the message count, and a snippet of the matching text.

Going back: /find-back

Every time you switch sessions — via /find, /resume, /new, /fork, or /clone — pi fires session_start with the file you just left. This extension records that onto a small navigation stack so /find-back replays it in reverse: a browser-style back across sessions and projects.

• Repeat /find-back to walk further back through the chain.
• Deleted sessions at the top of the stack are skipped automatically.
• A one-shot guard prevents ping-pong: the back-jump itself isn't re-recorded, so the next /find-back goes one step further, not back to where you were.

The stack lives in ~/.pi/agent/session-finder/backstack.json (honours PI_CODING_AGENT_DIR). It is on disk, not in memory, because a cross-project jump reloads this extension module and would wipe in-memory state. It is capped at 50 entries.

Where it works

/find is interactive (TUI and RPC modes). In print / JSON mode it is a no-op that points you at the (planned) pi --find CLI flag.

How it matches & ranks

• Scope: every session, every project.
• Match targets: session name, cwd, and the full allMessagesText.
• Default: case-insensitive AND of all terms (quoted phrases become one term). or / phrase modes are implemented and ready for a settings hook.
• Snippet: centered on the least-common matched term (a local IDF surrogate — rare terms disambiguate better), trimmed to token boundaries, whitespace-collapsed.
• Ranking: name hit first → more matched terms → more recent.
• Preview pane: focusing a match lazily parses that session's JSONL and shows the models used, a tool histogram, files modified (from edit/write calls), and cost · tokens consumed — above the keyword-centered snippet. Set PI_FIND_RICH_PREVIEW=0 to keep the pane snippet-only.
• Peek: once a row is focused, < / > page back/forward through the whole session transcript in the preview pane (step ≈ 0.8 of the window so context overlaps at the seam). The pane resets to the match anchor whenever you move to another row.
• Experimental RRF: set PI_FIND_RANK_MODE=rrf to fuse four independent signals (metadata, term coverage, recency, term frequency) via Reciprocal Rank Fusion instead of the hand-tuned order. Off by default — it becomes the default only if it beats the heuristic on the gold set. (bm25 is reserved and currently behaves like the default.)

Configuration

Env-var knobs (pi extensions don't expose a config API yet):

| Variable | Default | Effect | |---|---|---| | PI_FIND_RICH_PREVIEW | 1 | 0 disables the models/tools/files/cost facet pane (snippet-only). | | PI_FIND_RANK_MODE | heuristic | rrf fuses four signals via Reciprocal Rank Fusion; bm25 is reserved. | | PI_FIND_BACK_DEBUG | 0 | 1 appends a line per session_start / /find-back to session-finder/debug.log. |

Project layout

src/
├── index.ts     # factory: registers /find + /find-back; scan → rank → select → switchSession
├── history.ts   # pure back-navigation logic: record switches, suppress ping-pong, pop for /find-back
├── finder.ts    # custom TUI component: scrollable list + live fuzzy filter + rich preview pane
├── parse.ts     # JSONL parse → recap (intent/last action/outcome) + rich facets + match locator
└── search.ts    # pure helpers: parseQuery / matchSession / rankMatches / extractSnippet (+ projName, ago)
test/
├── history.test.ts   # unit tests for the pure back-navigation logic
├── search.test.ts    # unit tests for the pure search logic
└── wiring.test.ts    # smoke test: real module load + /find + /find-back registration + guards

search.ts has no pi imports, so the core logic is fully unit-testable.

Development

npm install
npm run check      # typecheck (tsc --noEmit) + tests (vitest)
npm test
npm run typecheck

Status & roadmap

• MVP (this release): /find via ctx.ui.select; AND matching over allMessagesText + name + cwd; jump via switchSession. Usable & shippable.
• Shipped beyond MVP: custom TUI finder with live filter + a rich preview pane (models / tool histogram / files modified / cost — PLAN item 1), </> peek paging through the transcript (item 5), RRF rank-fusion opt-in (item 6), recap-at-landing + match locator on jump (item 7), and /find-back universal back-navigation across sessions/projects. All in-memory (search) / on-disk (back stack), no DB/cache/index. See PLAN.md.
• v1: richer settings once pi exposes a config API; RRF default flip (gated on the gold-set benchmark, PRD §10).
• v1.1: pi --find CLI flag; matchMode (or/phrase) + rankMode: "bm25".
• v2: streaming results, fuzzy matching, optional content index.

See PRD.md for the full spec and RESEARCH.md for the evidence base behind the design decisions.

License

MIT