/handoff

name: handoff
description: Prepare a verified resumption brief when moving work to another agent, device, or session, including local-to-cloud coding handoffs, and start the receiving agent with `runpane handoff`. Use for "hand this off," "continue on my Mac," "give this to Codex," or "save where we are."

Handoff

You are the outgoing collaborator. Give the next person or agent the verified context, decisions, and lessons needed to pick up where you left off.

Capture what matters

• Preserve the goal, why it matters, constraints, non-goals, and decisions with their reasons. Distinguish approved work from suggestions.
• Verify the current state. Record completed work, remaining work, which checks (CI, QA, review) have run and which are still pending, meaningful failed attempts, blockers, and the next concrete action.
• Link authoritative instructions, plans, evidence, and artifacts. Make the brief self-contained and focused on what the next worker needs.
• Include pending approvals and the scope of authorized work. Treat launching the receiving agent as a separate, user-authorized action.

Make coding work portable

• Identify the repository, branch, exact commit, issue/PR, and relevant setup instructions. Include project-specific checks with their results and the revision they tested.
• Inspect staged, unstaged, untracked, and unpushed work. Separate task changes from unrelated edits and verify which revisions and files are available remotely.
• Transfer task-specific code and files through an authorized push or access-controlled destination. Preserve unrelated work and identify any files still awaiting transfer.
• Record required tools, services, and credential setup references. Keep secret values in their approved secret store and check the receiving agent’s plugin, skill, and network prerequisites.
• Keep private code and patches in access-controlled locations. Identify the next step needed to resolve any transfer or permission blocker.

Write the note

Write the brief as the handoff note in [references/note-template.md](references/note-template.md): a compaction of your session, in nine required `##` sections, for a reader with none of your context.

Start the receiving agent

When the person asks for another agent to continue, on this machine or another of theirs, use `runpane handoff`. It works the same from any harness. "Hand this to Claude on my Mac" authorizes starting that agent; it does not authorize pushing.

When you run in a Pane tab and the receiver is the same agent as you (Claude, Codex, Cursor or OpenCode), the handoff carries your own session: the receiver continues your conversation, not a fresh agent. On another machine, your session's files are copied into that machine's agent store and the receiver resumes the same session. On this machine, the receiver resumes a fork of it, because two agents never resume one session on one machine. Cursor has no fork, and a copied Cursor chat still writes to the original, so a Cursor session is carried only to another machine: on this one the handoff reports `not-continued`, starts nothing, and offers the note route. You still write the note: the receiver gets it as context, and it is all a fresh agent gets when the session can't be carried.

1. Find the machine's name: `runpane workspace list` lists the person's machines (a unique prefix such as `macbook-pro` works). Ask when more than one fits. 2. Get the template outside the checkout, so it is never committed: `runpane handoff --template > ~/handoff.md`. Fill in every section; write "None" where one does not apply. Leave the front matter alone, and don't add instructions for the receiver: the CLI rewrites the front matter and appends them when it sends. 3. Make the work reachable. Commit the task's files yourself; leave unrelated edits uncommitted. If the branch is not pushed, ask before pushing, then push it or pass `--push` (it commits every remaining change except the note as WIP and pushes; it never forces). 4. Check the destination: `runpane handoff "claude opus on <machine>" --note-file ~/handoff.md --dry-run`. The destination is freeform: the agent (claude, codex, cursor, or opencode to continue an OpenCode session), and optionally the model, the effort and the machine, such as `"codex gpt-5 high on parsa-devbox"` or `"cursor on this machine"`. `--machine`, `--agent`, `--model` and `--effort` override the text. Effort is supported for Claude and Codex; Cursor effort is rejected before committing or sending. The dry run's `continuity` says whether your session will be carried (`carried`, `sessionId`, `fork`, `files`, `bytes`) and, if not, why (`reason`). 5. Send it: the same command without `--dry-run`. It finds the destination's saved repository with the same remote, writes the note to that machine's `~/.pane/handoffs/`, and starts the agent. On another machine it gets a new Pane branched from yours; on this machine, run from the Pane that owns this checkout, it opens as a new tab in your Pane (1 feature = 1 worktree = 1 branch = 1 Pane), and the JSON's `receiver.route` and `receiver.reason` say which happened. If it fails, relay its message; it names the fix (Pane not running there, repository not saved there, branch not pushed). 6. Read the result. When your session is carried, the CLI checks that the receiver resumed it and shows its last message (see [continuity](../migrate-to-pane/references/continuity.md)), then tells the receiver to continue and where your note is (and where the session moved, when the folder or machine changed). Because you are the running agent, your own turn keeps appending to your transcript while the CLI forks it; that growth is allowed and reported as `checks.originalAppended`, while any change to what the transcript already held fails the check. JSON `continuity.result` is one of:

• `continued`: the receiver continues your session.
• `inconclusive`: the check could not tell. Follow `continuity.next`: ask the r