---
title: Handoff

sidebar:
  label: Handoff
  order: 2
---

Handoff controls what Metaphor does when an agent's work is ready.

With Handoff on, Metaphor verifies the work, commits and pushes the changes, and creates a pull request for you.

You can follow the agent's session and inspect its changes at any time. The pull request stays yours to review and merge.

## How Handoff works

The task runs in its own [worktree](/worktree). Handoff controls what happens when the work is ready.

With Handoff on, Metaphor:

1. Runs the agent in the task's worktree.
2. Verifies the work against the task's [checks](/checks).
3. Commits and pushes the changes.
4. Creates a pull request.

If verification finds an issue, Metaphor can send a follow-up back to the agent to continue working before the task moves forward.

:::note
Handoff doesn't merge changes into your repository. The pull request stays yours to review and merge.
:::

## Working without Handoff

Turn Handoff off when you want more control over what happens after the agent finishes.

The agent still works in an isolated worktree, but Metaphor leaves the final Git actions to you.

When the agent finishes, you can review the diff, continue working with the agent, commit locally, or commit and push when you're ready.

A pull request is created when you choose **Commit & Push**.

## Switching to Handoff during a task

You can turn Handoff on after a task has already started.

The change takes effect the next time you continue working with the agent. It doesn't immediately act on a run that has already finished.

When the next run is ready, Metaphor follows the Handoff workflow: verify the work, commit and push the changes, and create a pull request.

## Plan before making changes

With Handoff off, you can plan a task before the agent starts editing code.

The agent works through the approach without implementing it first. You can review the plan, refine the direction, and start implementation when you're ready.

Use planning when you want to agree on the approach before changes are made.

## Handoff on vs. off

| Behavior                   | Handoff on            | Handoff off                |
| -------------------------- | --------------------- | -------------------------- |
| Isolated worktree          | Yes                   | Yes                        |
| Checks                     | Automatic + your own  | Not available              |
| Review changes             | Yes                   | Yes                        |
| Commit and push            | Metaphor              | You decide                 |
| Pull request               | Created automatically | Created with Commit & Push |
| Plan before implementation | Not available         | Available                  |

## When to use Handoff

Use **Handoff** when you want Metaphor to take verified agent work through to a pull request.

Turn it **off** when you want control over when the work is committed, pushed, and turned into a pull request.