omp packages

@nicknisi/pi-recap0.1.8

Auto-recap card injected into the transcript after idle minutes

GitHub Actions Published 7 days ago MIT ~282 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

@nicknisi/pi-recap

Auto-recap card for pi. When a TUI session sits idle for a configurable number of minutes, this extension summarizes the current conversation branch with an LLM call and injects the result into the transcript as a dimmed, capped-height card. Useful when you come back to a session after stepping away and want a quick "where was I" without re-reading the whole transcript.

What it adds

  • Commands: /recap, /recap-idle
  • Entry type: recap (with a registered renderer)
  • Event hooks: session_start, before_agent_start, agent_settled, session_shutdown
  • Background timer (30s tick) that detects idle and fires the recap
  • No tools, keybindings, or overlays

Behavior

Idle is tracked via lastActivity, reset by before_agent_start and agent_settled (i.e. any agent run counts as activity). Every 30 seconds the timer checks:

  1. ctx.isIdle() — agent not running
  2. firedThisIdle — only one recap per idle period (reset on next activity)
  3. Elapsed time since lastActivity >= idleMinutes
  4. Branch has >= 4 message entries (skips trivial sessions; non-message entries don't count)
  5. The last message-bearing branch entry is not already a recap entry (so reopening a session that ended with a recap doesn't fire another one)

If all pass, it builds a plain-text transcript of the active context — the same compacted view pi sends the model (buildSessionContext), so history before a compaction is represented only by its summary. It includes user/assistant text plus one line per tool call: Tool <name> called with <args JSON>, with the args JSON capped at 200 characters. It sends it to the model with a "summarize tersely, 6-8 lines, short markdown headings" prompt, and appends the result as a recap entry via pi.appendEntry.

The renderer draws a Box containing a bold "Recap · " header and the summary as Markdown, capped at 5 lines (truncated with …). The card is dimmed and uses the theme's customMessageBg background so it reads as distinct from user/assistant messages.

Usage

/recap              # generate and inject a recap now
/recap-idle 5       # set idle threshold to 5 minutes (persisted)
/recap-idle abc     # rejected with a usage warning

Configuration

Config file: ~/.pi/agent/configs/recap.json (created on first /recap-idle write; read on every tick and every generation).

{
  "idleMinutes": 3,
  "model": { "provider": "anthropic", "id": "claude-haiku-4-5" }
}
Option Type Default Notes
idleMinutes number 3 Minutes of inactivity before an auto-recap fires. Set via /recap-idle.
model { provider: string; id: string } session model (ctx.model) Optional override. If omitted or not registered in Pi, recap uses the current session model.

No environment variables are read.

Constants (not configurable)

  • TICK_MS = 30_000 — idle check interval
  • MIN_BRANCH_LEN = 4 — minimum message entries before auto-firing
  • MAX_TOOL_ARGS_CHARS = 200 — per-tool-call args cap in the transcript
  • MAX_CARD_LINES = 5 — rendered summary line cap
  • Summarization call runs with reasoningEffort: "low", cacheRetention: "none"

Dependencies

Peer deps (all @earendil-works/*, provided by the pi host):

  • @earendil-works/pi-ai — uuidv7 (session id for the completion call)
  • @earendil-works/pi-coding-agent — ExtensionAPI, getMarkdownTheme; uses pi.registerCommand, pi.registerEntryRenderer, pi.appendEntry, pi.on, buildSessionContext, convertToLlm, ctx.sessionManager.getBranch, ctx.modelRegistry.complete, ctx.isIdle, ctx.ui.notify
  • @earendil-works/pi-tui — Box, Text, Markdown for the card renderer

No npm runtime deps, no workspace deps.

Caveats

  • TUI only: the timer and renderer are installed in session_start only when ctx.mode === "tui". /recap technically works in other modes but nothing renders the entry there.
  • Depends on several pi internals that could change across versions: sessionManager.getBranch(), modelRegistry.complete(), ctx.isIdle(), and the session_start/before_agent_start/agent_settled event names.
  • A configured model is resolved and completed through ctx.modelRegistry, so registered custom providers work. An omitted or unresolved override falls back to the current session model.
  • Background recap failures are reported as warnings and never terminate the pi process.
  • Entry content extraction is structural (filters blocks by type === "text" / type === "toolCall"), so changes to pi's message block shape would silently empty the transcript it summarizes.
  • The timer is cleared on session_shutdown; if a session never shuts down cleanly the interval lives until process exit.

Install

pi install /Users/nicknisi/Developer/pi-extensions/packages/recap