1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# `@amolith/pi-handoff`
 8
 9[![pi-handoff on NPM](https://img.shields.io/npm/v/@amolith/pi-handoff)](https://www.npmjs.com/package/@amolith/pi-handoff)
10[![Licensed under MutuaL-1.2](https://img.shields.io/badge/License-MutuaL--1.2-af2e1a?style=flat&labelColor=110402&link=https%3A%2F%2Fcodeberg.org%2FMutualism%2FMutualist-License)](https://codeberg.org/Mutualism/Mutualist-License)
11[![REUSE status](https://api.reuse.software/badge/git.secluded.site/pi-extensions)](https://api.reuse.software/info/git.secluded.site/pi-extensions)
12[![scratchanitch.dev badge](https://img.shields.io/badge/scratchanitch-dev-FFC4B5)](https://scratchanitch.dev)
13[![Liberapay donation status](https://img.shields.io/liberapay/receives/Amolith.svg?logo=liberapay)](https://liberapay.com/Amolith/)
14
15Get to the end of the thing you're doing, then use a subagent to extract
16relevant bits from the current session and create a new one from them with
17`/handoff thorough goal description`. You can tell Pi to hand something off
18because it has a handoff tool too.
19
20After extraction, whether triggered by you or Pi, the draft handoff goes in the
21new session's prompt editor and an auto-submit countdown starts that's cancelled
22by pressing most any key.
23
24## Install
25
26```sh
27pi install npm:@amolith/pi-handoff
28```
29
30## Do it yourself
31
32Run `/handoff` with whatever the next session should do:
33
34```text
35/handoff finish the release notes and publish both packages
36```
37
38If you omit the goal, Pi asks for one. Before the new session starts, the
39extension opens the generated handoff draft in the editor so you can review or
40tweak it. After the session switch, it starts an auto-submit countdown and
41pressing most any key cancels it.
42
43To use a different model in the new session, pass `-model provider/modelId`:
44
45```text
46/handoff -model neuralwatt/glm-5.1 finish the release notes
47```
48
49## Let the agent do it
50
51The package also registers a `handoff` tool. The agent should only use it when
52you explicitly ask for a handoff. It accepts:
53
54- `goal`: the goal for the new session
55- `model`: optional `provider/modelId` for the new session
56
57The handoff happens after the current agent turn completes and still opens the
58editor so you can tweak before starting the new session.
59
60## Configure the extraction model
61
62It uses the current session model by default. To use a cheaper/faster model, set
63a `provider/modelId` with one of these:
64
651. `--handoff-model provider/modelId`
662. `$PI_HANDOFF_MODEL`
673. `handoffModel` in `$PI_CODING_AGENT_DIR/settings.json`
68
69If you set more than one, that list is the precedence order.
70
71Example settings:
72
73```json
74{
75  "handoffModel": "neuralwatt/qwen3.6-35b-fast"
76}
77```
78
79If the configured value is malformed or doesn't match a registered model, the
80extension falls back to the current session model.
81
82## Ask about the old session
83
84New handoff prompts include the parent session path when available. The package
85registers a `session_query` tool so the next agent can ask focused questions
86about that prior session when the handoff summary isn't enough.