Hand off well-scoped implementation work from Claude Code to the Cursor CLI in headless mode, then review the diff and iterate — without leaving Claude Code.
- ✨ What you get
- ✅ Requirements
- 📦 Install
- 🚀 Using it
- ⚙️ Config
- 🧠 Repo context is inherited
- 🛡️ Safety properties
- 💡 Inspiration
An orchestrator where the expensive model only spends tokens on task contracts and patch review, while Cursor handles the code changes.
/cursor-handoff:handoff <task>— forward a self-contained instruction throughcursor-agent -p, review the diff, iterate./cursor-handoff:continue <chat-id> <feedback>— resume the same Cursor session with pointed feedback (session context is preserved)./cursor-handoff:orchestrate <big task>— three-tier mode:- The main model decomposes and reviews.
- One
handoff-managersubagent per task writes the executor prompt, runs the worktree-isolated handoff, verifies, and returns a patch + compact report. - Cursor does the code changes.
- Claude Code >= 2.x with plugin support
- Cursor CLI:
cursor-agent loginin a local terminal. Login is a browser flow; a headless handoff cannot complete it for you.- Alternative:
CURSOR_API_KEYalso works in non-interactive environments, although API-key usage may follow different Cursor API/SDK pricing than logged-in CLI usage.
- Alternative:
- GNU
timeoutonPATHfor watchdogs. On macOS, install coreutils sogtimeoutis available.
claude plugin marketplace add rebelliard/claude-plugin-cursor-handoff
claude plugin install cursor-handoff@rebelliard- Restart Claude Code after installing.
- Verify Cursor CLI auth once:
cursor-agent statusshould sayLogged in.- If it does not, run
cursor-agent loginand complete the browser flow before starting a handoff.
- Use namespaced slash commands:
/cursor-handoff:handoff/cursor-handoff:continue/cursor-handoff:orchestrate
Pick something mechanical but worth offloading: a small migration, repetitive test updates, or boilerplate across multiple files.
/cursor-handoff:handoff migrate dashboard settings forms from legacy FieldRow/Input to shared FormField/TextInput components; preserve labels, validation, and component tests
What happens, in order — you can watch it in the transcript:
- Claude forwards a compact self-contained instruction to Cursor: the user's request, essential file hints or verification, and "do not commit, stage, or push unless explicitly asked." The executor gets none of your conversation context, so the instruction must stand on its own.
- It runs the handoff through the plugin's hardened wrapper (never
cursor-agentdirectly), which prints aCHAT_ID— the resume handle — and aLOGpath. - Claude then reviews the resulting
git diffand re-runs the verification commands itself — the executor claiming success is not evidence. - You get a summary: what changed, whether checks pass, and the
CHAT_ID.
The result didn't quite land? Iterate in the same Cursor session — context is preserved, so feedback can be terse:
/cursor-handoff:continue last also update Storybook stories and tests that still import FieldRow; they should use FormField/TextInput now
One feedback round is the budget; after that Claude takes the task over itself. That's deliberate — looping a cheap executor on a task it keeps missing costs more than escalating.
For multi-part work, don't feed tasks in one at a time:
/cursor-handoff:orchestrate migrate dashboard route groups from inline loading spinners
to shared Skeleton states; split by route folder and keep Playwright smoke tests
passing
Orchestration keeps each execution lane isolated:
- Claude decomposes the work into file-disjoint tasks.
- Each task goes to a
handoff-managersubagent. - Each manager runs its executor pass in an isolated git worktree.
- Each manager verifies the result and returns a patch + ten-line report.
- Claude reviews each patch, applies and commits them sequentially, then re-runs verification on the whole.
- Your main checkout is never touched by an unattended run; you can keep working in it the entire time.
You can also skip the command and use natural language:
send the settings form component migration to Cursor
run the dashboard loading-state migrations by route folder in parallel
The cursor-handoff skill triggers on intent and applies the same delegation
rules.
The orchestrate prompt is read by your main model, so be explicit:
- Say what Claude should keep.
- Say what Cursor should execute.
- The default split is good: judgment stays, execution goes.
- Stating the split per task beats hoping for it.
Selective delegation — keep the judgment calls, route the typing:
/cursor-handoff:orchestrate add a compact density variant to the dashboard table UI.
Keep for yourself: the visual API, responsive behavior, and final review.
Send to Cursor: prop plumbing in Table, Toolbar, and row components; Storybook
examples; and interaction-test updates.
Engineering loop — iterate handoffs until a check is clean:
/cursor-handoff:orchestrate drive `pnpm lint --filter web` and
`pnpm typecheck --filter web` to zero errors. You triage accessibility rule
exceptions and public component API changes yourself. Send Cursor file-disjoint
batches of import cleanup, unused props, hook dependency, and test type fixes.
Every tier is pinnable:
- The orchestrator is whatever your session runs.
- Managers use their agent definition.
- The executor can be pinned per task with the optional
MODEL:contract field, or globally viaCURSOR_HANDOFF_MODEL.
For pure presentational prop rename batches, set MODEL: <fast executor model>.
Keep checkout, auth, and data-fetching routes on the default executor model.
- Keep these with Claude:
- Ambiguous design work.
- Taste-critical UI/API decisions.
- Security-sensitive changes.
- Browser verification is delegateable only when the target repo already provides a headless browser skill or an explicit command such as Playwright.
cursor-agentitself does not add browser tooling.
| Thing | Location |
|---|---|
| Run logs | ~/.cache/cursor-handoff/logs/<timestamp>-<chat-id>.log (14-day rotation) |
| Run metadata | ~/.cache/cursor-handoff/runs/<chat-id>.env plus latest.env for continue last |
| Worktrees | ~/.cursor/worktrees/<repo>/<name> (cleanup must remove both the worktree and its branch) |
| Resume a session by hand | scripts/cursor-run.sh continue <CHAT_ID> --workspace <WORKTREE> <prompt-file> |
| Env var | Default | Meaning |
|---|---|---|
CURSOR_HANDOFF_MODEL |
composer-2.5 |
Executor model (cursor-agent models to list) |
CURSOR_HANDOFF_TIMEOUT |
1800 |
Watchdog seconds for the executor run |
CURSOR_HANDOFF_AUTH_TIMEOUT |
30 |
Watchdog seconds for cursor-agent status |
CURSOR_HANDOFF_CHAT_TIMEOUT |
60 |
Watchdog seconds for cursor-agent create-chat |
Headless runs use the same agent runtime as the Cursor IDE:
- The workspace's
AGENTS.md,.cursor/skills/,.cursor/rules, and.cursor/mcp.jsonare loaded automatically. - Skills +
AGENTS.mdloading have been verified empirically. - Handoff instructions only need task-specific context, not repo conventions.
- In-place
newruns refuse a dirty working tree (override:--dirty-ok, or use--worktree). continueresumes in the recorded worktree when metadata is available; otherwise it requires--workspaceor an explicit--in-placeopt-in.--force/--trustare confined to the chosen workspace; worktree mode keeps unattended edits out of your checkout entirely.- MCP access is not auto-approved by default. Use
--approve-mcpsonly when the user explicitly asks for MCP-backed work, such as repo-provided browser tools. - Handoff instructions tell Cursor not to commit, stage, or push unless the user explicitly asks.
- Logs and metadata are stored with restrictive permissions, but logs may still contain prompts, diffs, and command output. Do not put secrets in handoff prompts.
This borrows the handoff shape popularized by codex-plugin-cc, adapted for Cursor's headless CLI and worktree flow.