> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hand off from a local agent

> Pipe uncommitted work from Claude Code, Cursor, or pi into an orq.ai agent session with the orq CLI.

Hand off unfinished work from a local coding agent to an **Orq.ai** agent session without committing or pushing first. The `orq sessions handoff` command sends the working-tree diff as a patch and starts a session whose first run sees the patch already applied in the cloned workspace.

## Prerequisites

* The `orq` CLI installed and authenticated (`orq login`).
* A [factory](/docs/ai-studio/ai-engineering/agent-sessions/factories-and-connections) whose policy allows the repository and agent.
* A local git checkout with the changes to hand off.

## Hand off the current diff

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git diff HEAD | orq sessions handoff \
  --factory "Platform engineering" \
  --prompt "Finish this change, run the tests, and open a pull request."
```

The command resolves the repository URL from the `origin` remote and the ref from the current branch, sends the diff on stdin as the `patch`, creates the session, and prints the session URL to stdout.

## Flags

| Flag           | Description                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--factory`    | Factory display name or `fac_…` id. Required.                                                                                                             |
| `--prompt`     | Prompt for the first run. Required.                                                                                                                       |
| `--patch`      | Unified diff to apply before the first run. `-` reads it from stdin (default pipe behaviour); a path reads it from a file. Omit to start a clean session. |
| `--repo`       | Repository HTTPS URL. `auto` (default) resolves `origin` from the local checkout.                                                                         |
| `--ref`        | Branch, tag, or commit to clone. Empty uses the current branch.                                                                                           |
| `--agent`      | Agent override. Empty uses the factory default.                                                                                                           |
| `--name`       | Session display name. Empty generates a `handoff-<timestamp>` name.                                                                                       |
| `--project-id` | Project id. Required for workspace-wide API keys; a project-scoped key can omit it.                                                                       |

## How the patch is applied

The patch is a unified diff, at most 1 MiB, applied with `git apply --3way` in the cloned workspace after the clone (or snapshot restore) and before the first run. The session log records a `session.patch_applied` event with the file, insertion, and deletion counts.

A patch that does not apply records `session.patch_failed` with the git message and the run still starts, so the agent can resolve the conflict markers itself. The patch is applied exactly once; pausing and resuming the session does not re-apply it.

## From a file instead of a pipe

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq sessions handoff --factory "Platform engineering" \
  --patch ./changes.diff --prompt "Review and finish the change."
```

## Continue an existing session

Use the [REST API](/docs/ai-studio/ai-engineering/agent-sessions/using-sessions) (`POST /v2/agent-sessions/{session_id}/runs`) or the session page to send the next message. The handoff command starts the first run; follow-up messages are continue runs on the same conversation.