---
title: "Hand off a session"
description: "Continue an active Claude Code, Codex, OpenCode, or Cursor session with a Hoplite cloud agent."
canonical_url: "https://hoplite.sh/docs/cli/handoff"
markdown_url: "https://hoplite.sh/docs/cli/handoff.md"
---

# Hand off a session
URL: /docs/cli/handoff
LLM index: /llms.txt
Description: Continue an active Claude Code, Codex, OpenCode, or Cursor session with a Hoplite cloud agent.
Related: /docs/cli, /docs/import, /docs/threads

# Hand off a session

`hoplite handoff` turns the session you're actively working in locally into a live Hoplite [thread](/docs/threads), so a cloud agent picks up where your local agent left off.

[Sign in](/docs/cli#sign-in) first with `hoplite login`, then run this from the repository where your local agent is working:

```bash title="terminal"
hoplite handoff
```

To follow the thread from your terminal afterwards, start `hoplite` and pick it with `/resume`, or open it in the Hoplite app.

## What gets uploaded

Hoplite selects the most recently active Claude Code, Codex, OpenCode, or Cursor session for the current repository, uploads its user/assistant conversation as an attachment, and starts a live cloud thread on the current branch. Tool output and hidden reasoning stay local.

The cloud workspace can only see files available from GitHub. Running development processes and ignored files are not transferred. Without `--autopush`, the command warns when uncommitted changes or unpushed commits will be missing from the cloud workspace.

Run `hoplite handoff --dry-run` to see the selected session and transcript without uploading anything.

## Push local changes first

To commit all local changes and push the branch before creating the thread, opt in explicitly:

```bash title="terminal"
hoplite handoff --autopush --prompt "Finish the PR"
```

## Options

| Flag | What it does |
| --- | --- |
| `--prompt TEXT` | Extra instructions for the cloud agent |
| `--autopush` | Commit local changes and push before creating the thread |
| `--dry-run` | Print the selected session and transcript without uploading or creating a thread |
| `--harness NAME` | Only consider `claude`, `codex`, `opencode`, or `cursor` sessions |
| `--cwd DIR` | Hand off the session for another directory |
| `--repo ORG/REPO` | GitHub repository, when the git remote doesn't identify it |
| `--branch NAME` | Branch for the cloud workspace. Default: the current branch |
| `--model ID` | Hoplite model for the thread |
| `--title TITLE` | Thread title |

## Let your local agent hand off for you

To let your local coding agent perform the handoff itself, install Hoplite's Agent Skill globally:

```bash title="terminal"
npx skills add CarbonCopyInc/skills --skill handoff-to-hoplite --global
```

Then ask the agent to `Use $handoff-to-hoplite to continue this session in Hoplite.` The skill checks the checkout and keeps committing or pushing local changes behind explicit authorization.

## Sitemap

Sitemap discovery is not enabled for this deployment.