description: Hand work to another tool, account or machine and pick it up there, in two words. Use when the user says "hand off", "out of tokens", "switching accounts", "pick up" or "continue". argument-hint: "[--reason \"...\"] [--next \"...\"]" version: 3.0.0

sw-handoff: "hand off" here, "pick up" there

The user should never have to copy a prompt. Two words each way.

Hand off

When the user says "hand off", "handoff", "I'm out of tokens", "switching to Codex" or "switching accounts", run:

specweave handoff --reason "<their words>"

It releases your task claims, records the handoff in the ledger, writes handoff.md next to the increment, pushes the branch, and pushes a snapshot of your uncommitted edits to the specweave-handoff branch (and wip/<branch>). Your working tree, index and branch are untouched. Relay its two or three lines as they are, then tell the user: say "pick up" in the other tool.

Add --next "<exact next step>", --gotcha "..." or --decision "..." only for what the files cannot tell the next agent. No Git remote and another machine: --inline prints a prompt to paste instead. --no-push keeps it local.

To hand off by itself, the user runs specweave auto-handoff on once (Claude Code and Codex, on their own machine; not in cloud sessions). A session then hands off at 90% of the 5-hour or weekly limit (--at <percent> to change it); auto-handoff status shows the current usage. When its Stop hook asks you to hand off, run the handoff it names.

Claude Code also warns the model itself near and at the 5-hour limit, with a note that starts "[Usage limit approaching" or "[Usage limit reached". Treat that note as the handoff moment: finish the current edit, run specweave handoff --reason "usage limit" (one command; it needs no summary from you) and stop.

Pick up

When the user says "pick up", "pick up here", "continue" or "continue from the other account", run specweave pickup. It fetches the last handoff, moves this branch forward to it and applies the handed-off edits (only on a clean tree), then prints the increment, the next task with its acceptance criteria and any notes. If it reports uncommitted changes or a diverged branch, do what it says; never discard the user's edits. Then continue with sw-do.

Notes and the record

• specweave note "<text>" leaves a message for whoever works on the increment next.
• specweave report writes an HTML timeline of who did what: tools, sessions,

handoffs, pickups, evidence.

Manual path (no CLI)

1. Release each task you hold by appending a line to its ledger.jsonl:

{"t":"T-03","e":"release","by":"codex@mbp","at":"2026-09-02T12:00:00Z"}, and a note for the next agent: {"t":"*","e":"note","by":"codex@mbp","at":"2026-09-02T12:00:00Z","note":"T-03 half done, see handoff.md"}. In PowerShell append with [IO.File]::AppendAllText and UTF-8 without a BOM, never >>.

1. Write .specweave/increments/<id>/handoff.md (UTF-8, no BOM) with these sections in

this order: ## Where I left off, ## Done / Pending, ## Decisions, ## Files touched, ## Next steps, ## Resume, and a last line <!-- Doc format v2 -->. Scrub tokens, keys and passwords from it first.

1. Commit the work in progress and push the branch:

git add -A
git commit -m "0042: work in progress (handoff)"
git push -u origin HEAD

To pick up by hand: git fetch origin, check out that branch, read its handoff.md, and continue at the first task in spec.md with no done line in the ledger.