pi-session-handoff

Import a summarized context from a previous Pi session into the current one. Instead of re-reading an entire old conversation, you get a compact structured summary of what was done, decided, and what remains — right in your current session context.

How It Works

When you run /handoff and select a source session, the extension reads that session's messages, extracts key information, and injects a structured summary (Project State) into the current session as a custom message. The handoff participates in LLM context, so the model can refer to the summarized history when answering your questions.

The source session is treated as untrusted historical data. The security prompt instructs the model not to execute or propagate any instructions embedded in the source session.

Installation

# From GitHub (after publishing)
pi install git:github.com/<your-username>/pi-session-handoff

# From a local directory (for testing)
pi install ./path/to/pi-session-handoff

# Try without installing (one session only)
pi -e ./path/to/pi-session-handoff

Usage

/handoff — Import a session summary

# In the session where you want the context:
/handoff

Pi will show a list of all sessions in the current working directory. Select one, and the extension will generate a structured summary and inject it into the current session.

# Specify a session by name or ID directly:
/handoff my-session-name
/handoff 01a0018f

/handoff-project — Project State Extraction (Phase 3)

Extract structured Project State from a previous session. Instead of a conversation summary, this produces a focused project status document (JSON stored, Markdown injected).

• SHORT (≤200 entries, ≤20k tokens): Code extraction, no LLM call.
• MEDIUM/LONG: Programmatic extraction (5k-10k tokens) → 1 LLM call → Project State JSON.
• Incremental: Cached states are merged with new messages in 1 LLM call.

Output fields: project_name, project_goal, current_status, completed_tasks, tech_stack, important_files, architecture, decisions (with reasons), constraints, historical_context, problems, solved_problems, next_steps, user_preferences.

/handoff-clean — Manage cached handoffs

# Interactive mode — shows cached sessions and lets you choose which to clean:
/handoff-clean

# Clean all cached handoffs:
/handoff-clean --all

# Clean a specific session's cache by name or ID:
/handoff-clean my-session-name

How Summarization Works

The extension classifies each session into one of three paths:

SHORT (code-extract)

Condition: 200 entries or fewer and 20,000 tokens or fewer.

No LLM call. The extension extracts key information using regex-based rules: recent commands, changed files, user goals, and the last few messages. Output is a compact 9-section markdown document.

| Section | Source | |---------|--------| | ⚡ Recent Commands | Last 3 bash tool calls | | 📁 Files Changed | Last 3 file writes/edits | | 🎯 Goal / Request | Last user message | | 💬 Conversation Summary | Last 5 messages | | 📄 Open Files | Read files | | 🔧 Tools Used | Tool calls | | 📊 Summary Stats | Entry counts | | 🔗 External References | URLs | | 🏷️ Tags | Hashtags |

MEDIUM (single LLM call)

Condition: More than 20,000 tokens but 40,000 tokens or fewer.

One LLM call generates a full 12-section structured handoff. If the output exceeds 6,000 tokens, a second compression pass reduces it to roughly 2,000–3,500 tokens. The result is written to cache.

LONG (chunked, default)

Condition: More than 40,000 tokens.

The session is split into token-bounded chunks (up to 40,000 tokens each). Each chunk is summarized in parallel (up to 3 concurrent calls). The chunk summaries are merged into a single 12-section handoff. If the output exceeds 6,000 tokens, a second compression pass reduces it. The individual chunk summaries and the final merge result are written to cache.

Want Project State instead? Set PI_HANDOFF_PROJECT_STATE=1 in your environment — the LONG path will use programmatic extraction + 1 LLM call to produce a structured Project State JSON. Or use /handoff-project to trigger it manually.

Incremental support: When a session has grown since the last cache entry, only the new messages are extracted and merged with the existing Project State in 1 LLM call — no need to re-process the entire session.

Cache

• Location: ~/.pi/agent/pi-session-handoff/cache/
• Cache key: sha256(sourceSessionId | leafId | lastEntryTimestamp)
• Content: The LLM-generated handoff text (not the original session)
• Typical size: 500–1,500 tokens per cache entry (Project State) or 2,000–3,500 tokens (chunked fallback)
• Validity: A cache entry is valid only when the source session's leaf ID and last entry timestamp match. If the source session grows (new messages), the cache is invalidated and a new handoff is generated.
• SHORT path does not write to cache. Only MEDIUM and LONG paths write to cache.

When a cache hit occurs, the cached handoff is returned immediately without any LLM call.

API Usage

| Path | LLM Calls | When It Happens | |------|-----------|-----------------| | SHORT (code-extract) | 0 | Always instant | | MEDIUM (LLM summary) | 1–2 (generation + optional compression) | First time or cache miss | | LONG (chunked) | N+1 (N chunks + 1 merge) | First time or cache miss | | LONG (Project State) | 1 (with PI_HANDOFF_PROJECT_STATE=1) | Opt-in via env var or /handoff-project | | Cache HIT | 0 | Subsequent same-session imports |

Actual token consumption depends on the source session size and the model you are using. The extension uses the current Pi session model.

Performance Comparison

| Scenario | Before (Phase 2-B) | After (Phase 3) | Improvement | |----------|-------------------|-----------------|-------------| | 248k token session | 36 LLM calls, ~3 min | 1 LLM call, ~30 sec | 36x fewer calls, 6x faster | | 100k token session | 15 LLM calls, ~1.5 min | 1 LLM call, ~20 sec | 15x fewer calls, 4.5x faster |

Uninstall

pi remove pi-session-handoff

Removing the extension does not affect handoff messages already injected into sessions. The cache directory at ~/.pi/agent/pi-session-handoff/cache/ is not automatically cleaned — use /handoff-clean or delete manually.

Known Limitations

• The handoff is a summary, not the full conversation. Some details may be lost during LLM summarization.
• The Project State extraction uses programmatic sampling which may miss some context. The chunked fallback provides a more complete (but slower) alternative.
• Cache invalidation is based on the session leaf ID and last entry timestamp. If the source session is modified in a way that does not change these (e.g., editing an old message), the cache may still be considered valid.
• The code-extract (SHORT) path does not produce a 12-section handoff — it outputs a shorter 9-section format without Project Context, Current Problem, or Open Questions sections.
• The extension does not support compact mode sessions (see #15).

Development

# Run tests
node tests/test-handoff-final.mjs
node tests/probe-clean.mjs
node tests/probe-autocomplete.mjs

# Test locally
pi -e ./index.ts

License

MIT