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
 30If you try it and find that it doesn't behave as expected, please send me your
 31session file, the goal, and the resulting handoff so I can debug. Contact me via
 32the methods listed at the bottom of [my website](https://secluded.site), or if
 33you know me elsewhere, you're welcome to DM me there.
 34
 35## Do it yourself
 36
 37Run `/handoff` with whatever the next session should do:
 38
 39```text
 40/handoff finish the release notes and publish both packages
 41```
 42
 43If you omit the goal, Pi asks for one. Before the new session starts, the
 44extension opens the generated handoff draft in the editor so you can review or
 45tweak it. After the session switch, it starts an auto-submit countdown and
 46pressing most any key cancels it.
 47
 48To use a different model in the new session, pass `-model provider/modelId`:
 49
 50```text
 51/handoff -model neuralwatt/glm-5.1 finish the release notes
 52```
 53
 54## Let the agent do it
 55
 56The package also registers a `handoff` tool. The agent should only use it when
 57you explicitly ask for a handoff. It accepts:
 58
 59- `goal`: the goal for the new session
 60- `model`: optional `provider/modelId` for the new session
 61
 62The handoff happens after the current agent turn completes and still opens the
 63editor so you can tweak before starting the new session.
 64
 65## Configure the extraction model
 66
 67It uses the current session model by default. Interactively select a
 68cheaper/faster model by running:
 69
 70```text
 71/handoff:set-extraction-model
 72```
 73
 74It opens Pi's model picker and saves the selected model in
 75`$PI_CODING_AGENT_DIR/settings.json` as `handoffExtractionModel`.
 76
 77You can also set a `provider/modelId` with one of these:
 78
 791. Startup flag: `--handoff-extraction-model provider/modelId`
 802. Env var: `$PI_HANDOFF_EXTRACTION_MODEL`
 813. Settings value: `handoffExtractionModel` in `$PI_CODING_AGENT_DIR/settings.json`
 82
 83If you set more than one, that list is the precedence order.
 84
 85Example settings:
 86
 87```json
 88{
 89  "handoffExtractionModel": "neuralwatt/qwen3.6-35b-fast"
 90}
 91```
 92
 93If the configured value is malformed or doesn't match a registered model, the
 94extension falls back to the current session model.
 95
 96## Ask about the old session
 97
 98New handoff prompts include the parent session path when available. The package
 99registers a `session_query` tool so the next agent can ask focused questions
100about that prior session when the handoff summary isn't enough.