# Handoff: continue in a fresh session
Every main-session tool call re-sends the whole conversation. This skill moves the work to a fresh session (about 80k tokens at start) before the context grows expensive.
**Local only.** The handoff file lives on the user's disk, and the next session must start on the same machine.
## Settings
Four env vars set the limits. Set them in the `env` block of `~/.claude/settings.json`. Unset means the default.
| Env var | Default | Meaning |
|---|---|---|
| `HANDOFF_HOP_CAP` | `3` | Automatic handoffs in a row before the user must approve. |
| `HANDOFF_TOKENS` | `500000` | Context size in tokens that fires the handoff trigger. |
| `HANDOFF_CALLS` | `100` | Tool-call count that fires the handoff trigger. |
| `HANDOFF_MODEL` | `opus` | Model of the new session (`--model`). Without it, the new session starts on the account default model, which can cost more. |
A hook reads all four. Its reminder states the hop cap. If no reminder showed the cap (a manual `/handoff`), run `echo ${HANDOFF_HOP_CAP:-3}`. Below, **CAP** means this value.
## Rules
- **In-phase handoff runs without the user** on the CLI path: the next steps are already in an approved plan and need no decision from them.
- **Phase break: stop and ask.** If the next step starts a new phase, or needs a decision only the user can make, do not launch. Ask through AskUserQuestion and send a push.
- **Hop cap: CAP (default 3).** A chain of automatic handoffs stops at hop CAP. Do not launch hop CAP+1. Send a push and stop.
- **One-way doors stay gated.** A handoff never authorizes a push to a shared branch, an external post, or a delete that was not already approved.
## Steps
### 1. Finish the current small step
Do not stop mid-edit. Finish the edit or command in progress, so the working tree is in a state the next session can read. Do not start a new step.
### 2. Classify the handoff
Decide one of:
- **in-phase**: the remaining work is a known next step in an approved plan, no decision is pending, and this is hop CAP or lower.
- **gated**: a phase break, a pending decision, an open question to the user, or a hop above CAP.
Read the hop number from the session's first prompt (`Handoff hop N (cap C)`). Use that C as CAP when it is present. When the user approves a gated handoff, the count resets: the next prompt says hop 1 (the user reviews every CAP hops). A session that did not start from a handoff is hop 0, so its handoff is hop 1.
### 3. Save state
1. Update the project's `status.md` with what was done and what is next. Commit it, with any finished work, on the current branch. Do not push unless the push was already approved.
2. Save any memory this session produced.
3. Write the handoff file: `<home>/handoffs/<YYYY-MM-DD-HHMM>-<slug>.md` (git-ignored, local). Contents:
- **Goal**: the task and its success criterion.
- **Done**: what this session finished, with commit hashes.
- **Next**: the ordered next steps. Mark the first one.
- **State**: the branch, uncommitted files, running processes and their ports.
- **Rules**: the project rules that apply, and any decision the user made in this session that the next session must keep.
- **Hop**: `N (cap CAP)`.
### 4. Pick the session name and write the starting prompt
**Pick the name once** (max about 40 characters): `<emoji> <Project> · <next step>`. Use one emoji only when it adds meaning, for example a game controller for a game, a palette for design, a wrench for tooling, a bug for a bug fix. Add `↪N` for hop N when the chain continues. Skip the emoji when none fits. Use this exact name in three places: the first line of the prompt, the `--name` argument (step 5), and the session title.
Write the prompt to `<home>/handoffs/<YYYY-MM-DD-HHMM>-<slug>.prompt.txt`, with the same ASCII slug as the handoff file. Do not put the emoji or "·" in the file name: a non-ASCII path breaks the terminal route. Keep the prompt self-contained. **The first line carries the name**, so a session that starts without the flag still gets a readable title.
**Never start the prompt with `/rename <name>`.** The CLI runs a first-line `/rename`, but it passes the whole prompt as the name and sends nothing to the model.
```text
Handoff hop <N> (cap <CAP>): <session name>
Continue the work from a previous session.
/project <name> (always, for project work: the session starts in the home folder, and /project loads the project)
1. Read <handoff file path> and <status.md path> first.
2. Then do the first step under "Next".
Run /handoff again when the trigger hook fires.
```
### 5. Hand off
**Every handed-off session starts with `--remote-control` and `--name`.** `--remote-control` turns on remote control even when a local setting overrides the global rule. The launch script adds both flags itself. Pass the name from step 4 as the third argument.
**`--name` renames the session like `/rename` does.** If a new session shows the prompt text as its title, it started without the flag.
**If gated:** do not launch. Send a push notification. Ask the user through AskUserQuestion whether to continue, and show the prompt in a fenced `text` block.
**If in-phase**, pick the path by the tools this session has:
- **Desktop app** (a `start_session` tool exists): call it with `initiation: "own_initiative"`, `context: "fresh"`, the prompt, and the session name as the title, and send a push. The card cannot pass `--remote-control`: tell the user in one line to check that remote control is on. The card can start on a fresh worktree, so commit all work in step 3, and keep absolute paths in the prompt.
- **CLI** (no `start_session` tool): run
```bash
bash <home>/scripts/handoff-launch.sh "<home>" "<prompt file>" "<session name>"
```
The work dir is **always** the home folder, never a project folder. A session started in a project folder asks for a new folder-access approval, and it misses the home instructions. The prompt reaches the project with `/project <name>`.
Pass both paths as absolute paths, never relative.
If the script fails, fall back to the gated path and include the error.
### 6. Stop
After the launch or the card, end the turn. Do not edit files in this session again: two sessions on one working tree can overwrite each other. Tell the user in one line that they can close this session.
## Setup (once, on the local machine)
1. Register the command with a symlink, not a copy, so edits to the skill reach the command:
```bash
ln -s <home>/skills/handoff.md ~/.claude/commands/handoff.md
```
2. Add the trigger hook to `~/.claude/settings.json` (user level, so it fires in every project), under `hooks`:
```json
"PostToolUse": [
{ "matcher": "*", "hooks": [ { "type": "command", "command": "node \"<home>/scripts/handoff-trigger.js\"" } ] }
]
```
3. Test the CLI path once with a prompt file that says "say hi". A new terminal window must open and run `claude`.
4. Pick where the CLI path opens the new session. Set the env var `HANDOFF_TERMINAL`:
| Value | Result |
|---|---|
| unset | A new terminal window. Runs `claude` so the session is interactive. |
| `vscode-terminal` | A terminal in VS Code that starts `claude` with the prompt. No Enter needed. |
| `vscode` | A Claude Code extension tab in VS Code. The prompt is prefilled: press Enter. Refuses a prompt over about 7,500 characters. It cannot pass `--remote-control` or `--name`: use `vscode-terminal` when you need them. |
| any other command | Used as the terminal launcher. |
`vscode-terminal` needs a one-time install of a small local VS Code extension. Reload VS Code after any change to its `extension.js`: VS Code keeps the old file in memory until a reload.