Session Handoff

Transfer work from one Pi session to another without losing context. This is the cross-session version of compact-safe — instead of compressing the current session, you're moving the work to a new session.

When to use

• Session is getting long (approaching compaction) and you want a fresh context
• You need to continue work in a different project or branch
• You're transferring work to a specialist session (e.g., handing a plan to a builder)
• The user says "handoff", "continue in a new session", "pass this to X"

Procedure

1. Write the handoff doc. The handoff extension (extensions/handoff.ts) writes a deterministic HANDOFF.md from recent turns + the last compaction summary. No LLM call — it's a snapshot. If the extension is available, it fires automatically. If not, write a markdown file to docs/handoff/<YYYY-MM-DD>-session-handoff.md with:

   • Active constraints — what must not change, what rules are in effect
   • Current state — what's done, what's in progress, what's blocked
   • Key decisions — what was decided and why
   • Errors (verbatim) — any error messages, stack traces, or failures
   • Next steps — what the receiving session should do first

2. Save key decisions to memory. Use the memory tool to save:

   • Architecture decisions (to project or memory target)
   • Failures and corrections (to failure target with category)
   • User preferences discovered during the session (to user target)

   Capture memory payload BEFORE validation — compaction can fire between return and parse. If memory is full, save to the handoff doc instead.

3. Discover the target session. Run intercom({ action: "list" }) to see active sessions. Filter by:

   • Same cwd (sessions in the same project)
   • Session name (if the user named it with /name)
   • Status (look for "idle" or "active" sessions that can receive work)

4. Notify the target session. Run intercom({ action: "send", to: "<session-id-or-name>", message: "..." }) with:

   • The handoff doc path
   • A 3-line summary of what to do next
   • Any blocking constraints ("don't touch X", "Y is in progress")

5. Confirm to the user. Tell them:

   • Where the handoff doc was written
   • Which session was notified
   • What the receiving session should do first

Rules

• The handoff doc is the source of truth. Memory is the backup. Intercom is the notification.
• KEEP constraints and errors verbatim — do not summarize them. The receiving session needs the exact error text.
• SUMMARIZE resolved decisions — don't replay the whole discussion.
• DROP prose and diary — keep only load-bearing context.
• If the target session doesn't exist or is unreachable, write the doc anyway and tell the user to start a new session pointing at the doc.
• Do NOT use this for in-session compression — that's compact-safe. This is for cross-session transfer.

Discovery without manual IDs

intercom({ action: "list" }) returns all active sessions with their IDs, names, cwd, and status. You don't need to know the session ID in advance — list first, then send. The session-status.ts extension also writes ~/.pi/agent/session-status.jsonl which any session can read for a quick overview.

Convention: when starting a new session in a project, run intercom list to discover other sessions in the same project. If any exist, send them your session ID + role so they know you're there.