Background agent handoff

Discussions
, ,
1

I really like using cursor 3, but I was a bit bummed that it doesn’t run in the background. I need to use my infra to run builds etc, so using the cloud agents was not an option for me.

To get around that, I vibe-coded a background agent skill that has kind of worked so far. Would love to hear if other people have tried something similar and how it’s gone.

name: background-agent-handoff
description: Launches a headless agent run with --print --output-format stream-json --trust --yolo, records the session id and repo-local handoff state, summarizes worker logs into a markdown checkpoint, and prepares both resume and interactive takeover prompts. Use when the user explicitly asks to hand off work to a background or headless agent, run the agent CLI independently, resume a prior headless agent run, or continue a headless run inside the current interactive Cursor harness.

Background Agent Handoff

Use this skill when

  • The user explicitly asks for a background or headless agent run.
  • The user wants to hand off a task, delegate work to the agent CLI, or resume a prior headless run.
  • The user wants to read what a headless worker already did and continue the task in the current interactive session.
  • The goal is to let a worker run independently, then return with a resumable state file.

Do not use this skill for normal foreground work.

Defaults

  • Launch headless with agent --print --output-format stream-json --trust --yolo.
  • Create a dedicated session id with agent create-chat and store it in the handoff file.
  • If the user specifies a model, pass --model <model>.
  • Store handoff state in the repo at .cursor/agent-handoffs/<handoff-id>/.

Run from the target repo root. If needed, pass --workspace <repo-path>.

Directory layout

For each handoff, create:

.cursor/agent-handoffs/<handoff-id>/
  handoff.md
  attempt-1.log
  attempt-2.log

Use a stable id like 20260407-fix-benchmark-timeout.

Start a new handoff

  1. Restate the delegated task as a concrete, self-contained instruction.
  2. Check for an already-running equivalent agent job before starting another one.
  3. Create .cursor/agent-handoffs/<handoff-id>/.
  4. Run agent create-chat and capture the returned session id.
  5. Write handoff.md from the template below with Status: running.
  6. Launch the headless worker and capture stdout and stderr to attempt-1.log.
  7. Record the exact launch command in handoff.md.

If agent create-chat fails or returns an empty id, stop and fix that first. Do not start an untracked run.

Command pattern:

chat_id="$(agent create-chat)"
agent --resume "$chat_id" --print --output-format stream-json --trust --yolo [--model MODEL] "FULL TASK PROMPT" > ".cursor/agent-handoffs/<handoff-id>/attempt-1.log" 2>&1

When running from Cursor, prefer starting the command in the background and polling it instead of waiting for the whole run synchronously.

Summarize the worker state

When the worker finishes, stalls, or the user asks for status:

  1. Read the latest attempt log.
  2. Use another agent to summarize only what is supported by that log.
  3. Update handoff.md with the summary, blockers, touched files, and copy-paste-ready prompts for both headless resume and headed takeover.
  4. Keep the raw log file; the markdown summary is a checkpoint, not a replacement.

The summary exists for humans, fresh agents, and the current interactive harness. The session id exists so a later headless run can continue the same chat with --resume.

Use a summary prompt like this:

Summarize this headless agent log for a follow-on agent. Be factual and do not infer unstated results.

Return markdown with these sections:
- Goal
- What it tried
- Files or areas touched
- Current state
- Errors or blockers
- Recommended next step
- Resume prompt
- Headed takeover prompt

If the run is still active, mark the summary as partial.

Resume a handoff

  1. Read .cursor/agent-handoffs/<handoff-id>/handoff.md first.
  2. Prefer the stored session id and reuse the Resume prompt section as the next prompt.
  3. Include the original task, the last known state, and any blockers that must be addressed next.
  4. Launch a new attempt log such as attempt-2.log.
  5. Update handoff.md:
  • set Status back to running
  • increment Current attempt
  • append the new command
  • replace Latest summary after the new run is summarized

If the stored session id is unavailable, create a fresh chat and seed it from the Resume prompt.

Resume command pattern:

agent --resume "<session-id>" --print --output-format stream-json --trust --yolo [--model MODEL] "RESUME PROMPT FROM handoff.md" > ".cursor/agent-handoffs/<handoff-id>/attempt-N.log" 2>&1

Continue in headed mode

Use this when the user wants the current interactive Cursor agent to take over a headless run.

  1. Read .cursor/agent-handoffs/<handoff-id>/handoff.md.
  2. Read the latest attempt-N.log if the summary is missing, stale, or too vague.
  3. Use the Headed Takeover Prompt section as the starting context for the current harness.
  4. Continue the task directly in the current session instead of launching another headless run.
  5. Update handoff.md to note that the task moved to interactive ownership and summarize what happened next.

Do not assume the interactive harness can directly attach to the headless chat session id. Treat handoff.md plus the latest log as the bridge.

Handoff template

Use this structure for .cursor/agent-handoffs/<handoff-id>/handoff.md:

# Background Agent Handoff: <handoff-id>

## Metadata
- Status: running
- Task: <original delegated task>
- Model: <default or explicit model>
- Session ID: <agent create-chat output>
- Workspace: <repo path>
- Started: <timestamp>
- Current attempt: 1

## Commands
```bash
<exact launch command>
```

## Logs
- `attempt-1.log`

## Latest Summary
- Pending.

## What It Tried
- Pending.

## Files Or Areas Touched
- Pending.

## Errors Or Blockers
- Pending.

## Recommended Next Step
- Pending.

## Resume Prompt
```text
Continue the delegated task below.

Original task:
<original task>

Latest known state:
<summary from latest attempt>

Next step:
<single concrete next action>
```

## Headed Takeover Prompt
```text
Continue this task in the current interactive Cursor session.

Original task:
<original task>

What the headless agent already tried:
<factual summary from the latest attempt>

Current state:
<current known state>

Blockers or open questions:
<blockers>

Next step to take now:
<single concrete next action>
```

## Final Outcome
- Pending.

Rules

  • Never delete prior attempt logs.
  • Never invent progress that is not visible in the log or artifacts.
  • Always keep handoff.md usable for both headless resume and interactive takeover.
  • Prefer one handoff directory per delegated task, with additional attempt-N.log files for retries or resumes.
4

I tried this out today, and it’s definitely janky. I find that this two layer model where you get updates via the agents means there are more chances for the agents to obfuscate or miss what actually happened. For exapmle, i realized that my background-agent ran into a particular type of authorization bug, but my sync did not include that.