In Pi.dev-Toolbelt, I introduce tools for working with Pi. The first is my extension pi-blitz-handoff. It handles a transition that eventually comes up during longer tasks: the conversation context is filling up, but the work is not finished.
Context is the information available to the language model when it produces its next response. Over a long session, requirements, decisions, files, results and discarded approaches accumulate. They are not all equally useful for continuing the work. A resolved debugging detour can take up a lot of space. A brief restriction from the user, meanwhile, may determine what the agent is allowed to do next.
That is what pi-blitz-handoff is designed to address. The extension asks the model to write a focused handoff dossier and passes it to a fresh Pi session as its first prompt. Pi's native session linking connects the new session to its predecessor, keeping the original transcript accessible. [1]
What needs to carry over?
A useful handoff needs to say more than “We are working on a website”. What is the current task? Which decisions still apply? What has actually been checked, and what has merely been changed? Where is the current state recorded? What action is authorised next?
The supplied default template explicitly asks for these distinctions. It also records blockers, unresolved questions and work that still needs approval. Session-specific runtime information is kept separate from the inventory of loaded skills. [1]
This matters especially when the direction has changed during the work. A discarded approach must not reappear as an agreed decision. A successful build must not turn into a passed browser test. And “finish it locally” must not become “publish it” in the next session.
Why not just compact the context?
Compaction condenses the existing context so the session can continue. pi-blitz-handoff focuses on a different question: What does a new session need to continue this particular task correctly? The extension is designed to capture that continuation context more precisely. That is its purpose, not a guarantee that every handoff will outperform every compaction. [1]
The difference is in the instructions given to the model and the subsequent transfer to a fresh session. The model writes the dossier; the extension handles the session transition and delivers the text. This also makes the limitation clear: a technically successful transfer can still carry an incomplete or inaccurate dossier.
And “Blitz” is my surname, not a promise of speed. A detailed handoff may take longer than compaction. [1]
Starting a handoff
Install the extension through Pi's package manager: [1]
pi install npm:pi-blitz-handoff
Within Pi, /sh requests a handoff. The extension first asks the model to establish whether the work has reached a suitable point for the transition. During active collaboration, it can present a Ready / Wait / Cancel choice. Once readiness has been accepted, the dossier is written and passed to the new session. [1]
Handoffs can also be triggered automatically based on context usage. This is off by default. “Automatic” only describes how the handoff is initiated. Whether the replacement session works autonomously, asks a question or waits still depends on the existing instructions and authorisation. [1]
During the transfer itself, new prompts are held back and passed on in their original order. If an interrupted handoff leaves those inputs behind, /sh-recover lets you explicitly inspect, execute or discard them. Leftover inputs are never executed automatically. /sh-cancel cancels an active handoff until the native session replacement has begun. [1]
Adapting it to the work
The extension includes three template profiles: Fast, Balanced and Precise. They differ in how much detail they transfer and how much context the replacement session is expected to reconstruct. Precise is the default. Templates can be customised and selected per project with /sh-project-template. [1]
The extension therefore does not impose a particular workflow. A template describes what the handoff should preserve. It does not grant additional permission.
What it does not carry over
A dossier transfers information. It does not move running background agents or shell connections into the new session. Their state and ownership need to be checked against the actual runtime environment there.
Your data also remains your responsibility. Dossiers and deferred inputs may contain confidential project information and are processed or stored as plain text. The extension provides neither automatic secret detection nor encryption, and it is not a sandbox. Like other Pi extensions, it runs with the permissions of the Pi process. [1]
Version 1.2.4, described here, requires Node.js 22.19.0 or later, Pi 0.84.2 or later, and an interactive, persisted Pi session. Sessions using --no-session are not supported. The source code is available under the MIT licence. [1], [2], [3]
pi-blitz-handoff is not meant to hide the restart. It is meant to leave a clear record of where the work stands and how it is authorised to continue.