pi-handoff

Session handoffs for the pi coding agent. When a session ends or runs out of context, pi-handoff writes a handoff document and starts a successor session from it — no lost context, no half-adopted subagent runs.

A community fork of @tifan/pi-handoff. It works on a plain pi install; the terminal-tab backend is optional.

Fork notice: This package is a fork of @tifan/pi-handoff 2.2.2, published to npm as @jyyyeung/pi-handoff. It vendors upstream's child-naming core (from @tifan/pi-rename 0.6.0), adds a dependency-free backend selector, and is not tracking upstream changes automatically. NOTICE.md lists every local change.

Features

Features that work everywhere:

• Structured handoff document — verify-first command list, state with SHAs/paths/task IDs, governing decisions, next steps, suggested skills, open questions. Generated by a model from the real conversation, never from a template.
• Verify-first checklist — the generated document opens with exact one-line commands the successor runs before trusting any state claim (repo status, task board, CI, live sessions).
• Governing decisions — every binding decision that constrains the next session is listed with its source and date, including decisions made in sibling sessions, or marked None recorded.
• Smart child naming — naming core from pi-rename: explicit focus > parent session name (prefix stripped) > rename model > first real user message fallback, with synthetic-message filtering.
• Configurable session_query model — the session_query tool resolves its model from the configured rename model, then the session model.
• In-flight subagent-run adoption — budget handoffs list still-active subagent runs with a recovery line, so the successor does not silently abandon them.

Features added by the tab backend (PI_HANDOFF_BACKEND=tab, or auto on a herdr machine):

• Verified prompt delivery — the prompt is sent through herdr --wait and cross-checked via status polling, with one automatic retry if delivery is not confirmed.
• Parent tab retirement — the originating parent tab is marked [handed-off] so you can see at a glance that it has been superseded.
• Budget-aware auto-close — when the handoff reason is budget exhaustion, the parent tab auto-closes after 3 seconds. Opt out with PI_HANDOFF_KEEP_TAB=1. Voluntary handoffs keep the parent tab open.

Install

pi install npm:@jyyyeung/pi-handoff

Then restart pi (or /reload). If you prefer hand-editing, add the package path to the packages list in ~/.pi/agent/settings.json — but pi install is the supported path.

From a local checkout:

pi install ./pi-handoff
pi -e ./pi-handoff/src/index.ts

Optionally install a handoff skill (any pi skill whose name is exactly handoff) to replace the built-in document policy with your own.

Quick start

In any TUI session, type the -handoff marker, optionally with a focus for the next session:

-handoff finish the auth refactor and get CI green

pi-handoff then:

1. generates the document from the real conversation, behind a Generating handoff with <model>… loader (Esc cancels the handoff);
2. writes it to $TMPDIR/pi-handoffs/pi-handoff-<date>-<focus-slug>.md and shows the path in a notice;
3. starts the successor session and hands it that path plus the handoff prompt.

The successor opens already knowing what to verify first, what state the work is in (with SHAs and paths), which decisions are binding, and what the next steps are. Type -handoff alone to use the default focus, continue the current work.

How a handoff runs

Two backends, same document. Pick with PI_HANDOFF_BACKEND:

Accepted aliases: inprocess / session / new-session for in-process, herdr / terminal for tab. Anything else falls back to auto.

On a machine without herdr, auto resolves to in-process: you still get the document and a successor session that has already received the prompt. The tab backend only changes where the successor runs and adds delivery verification, parent-tab retirement, and budget auto-close.

Requirements

Scope and non-goals

• Not a session store. The document is a starting point for a new session, not a resumable snapshot; the successor's context is the document plus whatever it reads itself.
• Not a summarizer. It targets continuation, not compression: decisions, state, and next steps, with the evidence needed to re-verify them.
• No automatic handoff on every turn. Nothing in this package watches your token usage. -handoff is explicit, and the only other entry point is the --reason=budget form of the bridge command, which a budget-aware caller has to invoke itself.
• Never invents state. The document is generated from the conversation only; anything unverified lands under open questions.

Troubleshooting

Nothing happens when I type -handoff. It only triggers in TUI sessions (input hook is disabled outside TUI mode). The marker must be a standalone token: -handoff (or x -handoff y), not -handoffs or handoff. Use PI_HANDOFF_BACKEND=in-process if you want to rule out backend detection.

The document was written but no successor session opened. Check the notice printed at handoff time. With PI_HANDOFF_BACKEND=tab, a missing workspace warns and falls back to in-process; a herdr failure is reported instead of silently dropping the prompt.

The document is thin or wrong. It is model-generated from the conversation; a short session gives a short document. Use the focus text (-handoff <what matters>) to steer what the successor is for. The file is plain markdown in $TMPDIR/pi-handoffs/ — edit it there if you want the successor to start from a corrected version.

The handoff files disappeared. They live in the OS temp directory ($TMPDIR/pi-handoffs/), which the system reclaims. Copy anything worth keeping into the repository it belongs to.

A handoff skill I installed is being ignored. Discovery looks for a skill named exactly handoff; a differently named skill is not used. When none is found the built-in policy runs and a warning says so.

Credits

Forked from @tifan/pi-handoff 2.2.2 (packages/pi-handoff), © Tifan Dwi Avianto, MIT. Child-naming core from @tifan/pi-rename 0.6.0 (packages/pi-rename), © Tifan Dwi Avianto, MIT. NOTICE.md lists every local change this fork carries; upstream has no obligation to accept them, and this package does not track upstream automatically.

Related packages

Other extensions from the same author:

Development

npm install
npm run typecheck
npm test

License

MIT — Tifan Dwi Avianto (upstream) and jyyyeung (fork).