pi-handoff

Handoff extension for pi coding agent — transfer context to a new session. Ported from omp (oh-my-pi)'s SessionHandoff.

Instead of compacting (which is lossy), handoff asks the model to write a structured handoff document capturing the exact technical state (decisions, files, next steps), lets you review/edit it, then opens a new session seeded with that context — so the next thread continues seamlessly without the old conversation.

Installation

pi install npm:@jackice/pi-handoff

Or install from a local path:

pi install /path/to/pi-handoff

Restart pi or run /reload to load the extension.

Requirements: pi-agent v0.84.0 or later (extensions API, session_before_compact event)

Usage

/handoff                      # generate a handoff document (auto-summarizes the current session)
/handoff continue the second phase of the plan  # with a focus instruction; the document will focus on that goal

Flow: generate handoff document → review/edit in the editor → confirm → new session opens with the document injected as <handoff-context> (the agent reads it and continues seamlessly).

Auto-save on compaction (optional, off by default)

When enabled, pi-handoff listens for session_before_compact and generates a handoff document before your context gets compressed — the state that would otherwise be lost is preserved on disk. It only writes the file; it never switches sessions.

Enable via CLI flag:

pi --handoff-auto-save

Or via config file ~/.pi/handoff.json:

{ "autoSaveOnCompact": true }

Saved documents live next to the session (same layout as omp): ~/.pi/agent/sessions/--<project>--/<session>/handoff-<timestamp>.md

Features

• Structured handoff documents — the prompt template (ported verbatim from omp) enforces Goal / Constraints & Preferences / Progress / Key Decisions / Critical Context / Next Steps
• Editor confirmation — review and adjust the document before it becomes the new session's context
• Parent tracking — the new session records the previous session as its parent, so /resume navigation keeps the lineage
• Compaction-aware serialization — compaction summaries and entries kept since the last compaction are included
• System prompt continuity — generation runs with the current session's system prompt, so the document reflects your project context and tooling

How It Works

/handoff [goal]
    │
    ├─ serialize current branch (compaction-aware)
    │
    ├─ oneshot LLM call: history + handoff template (with focus) → handoff document
    │
    ├─ editor: review / edit / cancel
    │
    └─ ctx.newSession({ parentSession, setup: inject <handoff-context> })

Development

bun install
bun test        # unit tests for pure logic (template rendering, context wrapping, paths)

License

MIT