# Handoff

You started a task on your Mac, but the next step needs Windows. `runpane handoff` sends your note and starts an agent (Claude, Codex, Cursor or OpenCode) in a new [pane](/docs/panes-and-worktrees) on the destination machine, from your commit. Handing off to the same agent carries your conversation with it.

You can also hand work to another agent on the same machine. Run `runpane handoff` from inside a pane, and the receiving agent opens as a new tab in your pane, on the same branch.

Use [Workspaces](/docs/runpane-workspaces) to run a command or read a file on another machine. Use Handoff when you want an agent there to take over the task.

## What you can ask

| You ask | The agent |
| --- | --- |
| "Hand this off to Codex on the devbox." | Writes the note, asks you before pushing, checks the destination with a dry run, then starts Codex there. |
| "Continue this on my Mac." | Hands off to its own agent type, so the receiver resumes this conversation. |
| "Give this to Claude in a new tab." | Opens Claude as a new tab in this pane. |
| "Push whatever's left and hand it off." | Adds `--push`. |
| "Move this Session to my devbox." | Recreates the [Session](/docs/sessions) there, with the note. |

## Before you start

1. Use the npm CLI (`npm i -g runpane`). The Python wrapper doesn't run Handoff.
2. Handoff refuses to send from an unpushed branch, even on the same machine.
3. For another machine, set up [Workspaces](/docs/runpane-workspaces). Open Pane on both machines. Then either link them by pairing the Pane app with each one ([Your computers](/docs/your-computers)), or sign in to Tailscale with the same login on both.
4. Save a native (non-WSL) clone of the repository in Pane on the destination. It needs a Git remote for the same repository and permission to fetch your branch. Install and sign in to the receiving agent there.

## Send a task

1. Find the destination's name:

   ```bash
   runpane workspace list
   ```

2. From your repository, create a note outside the checkout:

   ```bash
   runpane handoff --template > ~/handoff.md
   ```

   Fill in all nine sections below. Leave the front matter alone. The CLI fills in the current Git state and adds instructions for the receiver when it sends.

3. Commit the files the task needs and push your branch. Leave unrelated changes out. The receiver starts from the commit, so uncommitted files won't travel with it.

4. Preview the destination. Replace `my-windows-pc` with the name from step 1:

   ```bash
   runpane handoff "codex on my-windows-pc" --note-file ~/handoff.md --dry-run
   ```

   This checks the destination, note and Git state, and sends nothing. It doesn't start the agent, so it can't prove the agent is signed in.

5. Send the task by removing `--dry-run`:

   ```bash
   runpane handoff "codex on my-windows-pc" --note-file ~/handoff.md
   ```

   The CLI finds the saved repository with the matching remote, writes the note under `~/.pane/handoffs/` on the destination, and starts the agent. Use the check command it prints to inspect it. Stop editing the sending branch once the receiver takes over.

## Choose the agent and machine

The destination text names the agent. You can add a model, an effort level, and a machine name or unique prefix:

```bash
runpane handoff "claude opus on my-mac" --note-file ~/handoff.md --dry-run
runpane handoff "codex gpt-5 high on my-windows-pc" --note-file ~/handoff.md --dry-run
runpane handoff "cursor on this machine" --note-file ~/handoff.md --dry-run
```

Choose a model your installed agent can use. `--machine`, `--agent`, `--model`, and `--effort` override the text. Claude and Codex support effort selection. Cursor effort is rejected before anything is committed or sent. If several saved clones match, pick one with `--repo <selector>`.

## Same agent, same conversation

You still write the note; the receiver gets it as context.

- **Another machine:** the session's files are copied to that machine's `~/.claude`, `~/.codex` or `~/.cursor`, and the receiver resumes it. Cursor here is best effort.
- **This machine:** the receiver resumes a fork. Cursor can't fork, so it starts nothing and reports `not-continued`.
- **OpenCode** can only receive an OpenCode session.

The CLI then checks the receiver and reports:

| Result | What it means |
| --- | --- |
| `continued` | The receiver continues your session. |
| `inconclusive` | The check couldn't tell. Ask the receiver what it was last working on. |
| `not-continued` | Exits 1 and keeps the receiver. `--note-only` starts a fresh agent with the note instead. |
| `fresh-agent` | A new agent with your note: from `--note-only`, a different agent, or no session to carry. |

## What goes in the note

Keep the exact `##` headings from the template. Missing or empty sections are rejected. Write `None` when a section doesn't apply.

| Section | What to write |
| --- | --- |
| Goal | What you're trying to finish and what done means. Link the issue or PR. |
| Current state | Where the task stands now. |
| Done and verified | What you finished, the checks you ran, and their actual results. |
| In progress | Partial work, failing checks, and exact errors. |
| Next steps | Ordered actions, starting with one the receiver can do immediately. |
| Decisions and constraints | Your choices, reasons, permissions, and failed approaches. |
| Open questions | Unresolved questions and pending approvals. |
| How to verify | Commands to build, test, and see the result, with expected outcomes. |
| Git state | Repository, branch, commit, push status, and relevant uncommitted files. |

Don't put secrets in the note. Name the approved place to get them. Link evidence instead of claiming checks you haven't run.

## Let the CLI commit and push

If you've approved sending all remaining work, you can add `--push`:

```bash
runpane handoff "codex on my-windows-pc" --note-file ~/handoff.md --push
```

> **Warning:** `--push` commits all remaining changes as WIP and pushes the branch. It never force-pushes. Commit task files yourself first if the checkout contains unrelated work. A note saved inside the checkout is left out, and must not be staged.

Asking an agent to hand off a task lets it start the receiver. It doesn't by itself authorize a push.

## Hand off a Session

Run `runpane handoff` from a Session's terminal, or choose **Move to machine…** in the Session's right-click menu. It skips Git, writes the note to the other machine, and creates a Session there with the same name, goal and agent. With the same agent, the new Session resumes your conversation when you first open it.

The destination needs Pane running, and no saved repository. The original Session stays. A Session can't move to the machine it's on.

## How the receiver reports back

The CLI appends instructions to read the repository's `AGENTS.md`, check the starting commit, run your verification steps, and continue from your next steps. It tells the receiver to push to your original branch without forcing.

When you send from a Pane panel, the receiver gets a command like this, with your machine and panel filled in:

```bash
runpane workspace <origin_machine> panels submit --panel <origin_panel> --text "<result, commit or PR, and blockers>" --yes
```

If there's no sending panel, the instructions ask for a PR comment or a commit message on the branch instead.

## Current limits

- **WSL receivers aren't supported.** Explicit WSL destinations and saved WSL repositories on the receiving machine are rejected before committing or sending. Sending from WSL to a native Windows repository is supported.
- **Password-protected machines:** connect once from **Settings → Remote Access → Computers** and enter the password. `runpane workspace` then sends it.
- **Remote shells are limited.** Bash, Zsh, Sh, Fish, and PowerShell are supported. Windows `cmd` isn't.
- **An older Pane on the destination** that can't resume a carried session is refused before anything is sent. Update it, or use `--note-only`.
- **If startup fails after the note is sent,** inspect the destination's Sessions and existing Pane before retrying so you don't create a duplicate.

See [runpane CLI](/docs/runpane-cli) for the rest of the CLI.
