# pi-handoff

Handoff extension for pi coding agent — transfer context to a new session. Ported from [omp](https://github.com/can1357/oh-my-pi) (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

```bash
pi install npm:@jackice/pi-handoff
```

Or install from a local path:

```bash
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:

```bash
pi --handoff-auto-save
```

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

```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

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

## License

MIT