pi-sessions

pi-sessions turns your old Pi sessions into something you can actually reuse. It gives you search, follow-up Q&A, deliberate handoffs into new child sessions, automatic session titles, and a local index that keeps future sessions searchable.

Screenshots

Session lookup

Handoffs

Ask about old sessions

Install

Requires Pi 0.80.2 or newer and Node >=24 <26.

From npm (recommended):

pi install npm:pi-sessions

If you want to run directly from a local clone while developing:

pi -e /absolute/path/to/pi-sessions

Quick start

1. Install the package.
2. Open Pi and run /session-index.
3. Press r to build the index for all your prior sessions.
4. Try the main flows:

What session did I implement the db layer?

/handoff i want to implement the frontend component now

Features

| Extension | Surface | What it does | | ------------------ | ------------------------------------- | ------------------------------------------------------- | | Session Search | session_search pi tool | Search through old sessions | | Session Ask | session_ask pi tool | Ask questions about old sessions | | Session Handoff | /handoff, session_handoff pi tool | Start a focused new session; alternative to compaction | | Session Messaging | session_send_message pi tool | Send messages between running Pi sessions | | Session Picker | Alt+O | Reference old sessions in your prompt | | Session Index | /session-index slash command | Shows index status and rebuilds the local session index | | Session Auto Title | in background, /title slash command | Give sessions titles |

Session Search

session_search searches the local session index by text, repo, cwd, time range, file evidence, and whether a session is currently running.

Queries support regular text for normal usage, quoted phrases, AND / OR / NOT, parentheses, and -term negation when matching needs to be stricter. Unquoted terms use prefix matching, quoted terms are exact. A search with no query returns matching sessions chronologically, newest first. Use live: true to restrict results to currently running sessions.

File filters distinguish read-or-write evidence from write-only evidence:

• files.touched: sessions that read or changed a path
• files.changed: sessions that changed a path

Session Handoff

/handoff <goal> starts a focused new session. Give pi a goal, and it will generate a prompt for you to review before kicking it off.

You can either start a new session directly in your current one, or if you have Ghostty on macOS, you can spawn a new one in a split-pane and continue in your current:

• /handoff --left <goal>
• /handoff --right <goal>
• /handoff --up <goal>
• /handoff --down <goal>

The flag indicates the Ghostty split direction.

Flow:

• run /handoff [--<direction>] <goal>
• review the generated prompt preview
• optionally edit the prompt
• start the new session

If you do nothing, the preview autostarts after a short countdown.

When running in Ghostty on macOS, pi-sessions also exposes a session_handoff tool. This lets the agent start a background handoff after you choose a split direction. The current session keeps running, while the child session opens in the requested split, gathers context, and shows the same review countdown before starting.

If background handoffs ever target the wrong pane, run /handoff --identify from the intended source pane to refresh the in-memory Ghostty terminal binding.

Session Messaging

Agents can coordinate with other currently running Pi sessions:

• session_search with live: true lists live sessions
• session_send_message sends a message to another live session

Incoming messages start the recipient agent when idle and steer it when already running. Inactive sessions cannot receive messages, but you can still use session_search and session_ask with them.

Session picker

Directly reference prior sessions by looking them up by contents.

• shortcut: Alt+O
• press Tab to switch between current folder and all sessions
• type to filter results
• press Enter to insert a session id into your prompt

Handoff setting

If you want to override the shortcut, put this in your ~/.pi/agent/settings.json:

{
  "sessions": {
    "handoff": {
      "pickerShortcut": "alt+p"
    }
  }
}

Session Index

By default, pi-sessions will start indexing all conversations moving forward. If you want to backfill all prior conversations:

• run /session-index
• hit r to (re)index everything

this is idempotent, so if you run into any issues, or disable pi-sessions for a while, feel free to re-index to see if that resolves anything.

By default the index lives at:

~/.pi/agent/pi-sessions/index.sqlite

but you can change the location in ~/.pi/agent/settings.json:

{
  "sessions": {
    "index": {
      "dir": "~/.pi/agent/pi-sessions"
    }
  }
}

Session Auto Title

The auto-title extension keeps your session list readable by:

• Setting a title based on initial prompt
• Reevaluating the title every 4 turns to see if it should be updated

To manage existing titles, run /title, where you can:

• Regenerate a title for the current session
• Generate titles for all sessions in the folder
• Generate titles for all sessions across pi

Note that generating titles for all sessions can take some time, and will hit your configured model with the full contents of all sessions.

• automatic retitles run every few turns
• if you manually rename a session with /name, automatic retitling pauses for that session
• Regenerate the title for the current session to resume automatic retitling
• if unconfigured, it will attempt to use these models in order, first one that is available:
  • google/gemini-flash-lite-latest
  • anthropic/claude-haiku-4-5
  • openai/gpt-5.4-mini
  • your currently configured model

To change auto-titling settings, edit ~/.pi/agent/settings.json:

{
  "sessions": {
    "autoTitle": {
      "refreshTurns": 4,
      "timeoutSecs": 15,
      "model": "anthropic/claude-haiku-4-5",
      "prompt": "Custom prompt that overrides the default."
    }
  }
}

Development

npm install
npm run check
npm test

For an end-to-end manual flow, see SMOKE.md.