Cursor Copilot

Cursor Copilot

Cursor Composer 2.5 Fast is a subagent army you command through the cursor-pilot tmux wrapper. Spawn a job, drive its turns, read its output, bring back the result. Same base tech as codex-orchestrator and opus-agent-orchestrator - a different model with different strengths.

The Command Structure

SAINT - The King / CEO
    |
    +-- CLAUDE / CODEX (Orchestrator) --- General / Commander
            |-- CURSOR subagent (research)
            |-- CURSOR subagent (implementation)
            +-- CURSOR subagent (QA / browser-harness)

You are the orchestrator. You decide which Cursor subagents to spawn, write their briefs, drive their turns, and synthesize their output. Cursor agents are fast specialists - they do bounded work well and return quickly. You keep the strategic context.

When To Reach For Cursor

• Fast, bounded, well-scoped work. Composer 2.5 Fast is quick and cheap. Hand it a tight brief with a clear stopping condition.
• Parallel offload. Spin up a Cursor agent to QA or research while you keep building elsewhere.
• Browser QA. Cursor + browser-harness is the fastest path to real E2E verification (see QA mode). QA mode also exposes AgentMail for email OTP, magic-link, sign-up, and mailbox polling flows.
• A second model's eyes. Cursor sees code differently than Codex or Opus.

Keep deep, high-context implementation on Codex. Use Cursor for scoped sub-tasks with a sharp boundary.

Pick A Mode

Every run is one of three modes. Read the matching reference file for the brief contract, the right CLI flags, and the output schema:

Default invoke with no mode = read this file, then infer the mode from the task and confirm, or ask which mode fits.

--browser-harness is a cursor-pilot wrapper flag, not a native Cursor Agent CLI flag. Use it on cursor-pilot start for QA / browser jobs so the wrapper injects the local browser-harness Cursor plugin, includes the browser-harness and AgentMail skill context, and passes the right underlying Cursor Agent options. --force is also supplied to cursor-pilot; the wrapper passes it through to Cursor Agent as force-allow for autonomous tool calls.

The Core Loop

Every mode rides the same loop. The brief and flags differ; the mechanics are identical.

# 1. Start a live interactive job (mode-specific flags - see the reference file)
cursor-pilot start "<brief>" --dir /path/to/repo --force

# 2. Wait for the current interactive turn to finish
cursor-pilot await-turn <jobId>

# 3. Read the live pane / result
cursor-pilot capture <jobId> 220 --clean

# 4. Follow up / retest in the same session
cursor-pilot send <jobId> "<follow-up>"
cursor-pilot await-turn <jobId>
cursor-pilot capture <jobId> 220 --clean

# Scripted one-shot JSON mode remains available when needed
cursor-pilot start --headless "<brief>" --dir /path/to/repo --force

List and manage running work:

cursor-pilot jobs --json        # running and recent jobs
cursor-pilot status <jobId>     # one job's full state
cursor-pilot watch <jobId>      # live-tail output
cursor-pilot kill <jobId>       # stop a job
cursor-pilot clean              # archive old jobs, kill orphaned sessions

Writing The Brief (universal rules)

Every brief is a contract. Name the destination, the boundary, and the stopping condition. Each mode reference gives a fill-in template.

Goal: <one sentence - what this run produces>

Success means:
- <concrete checkable outcome 1>
- <concrete checkable outcome 2>

Stop when: <the exact condition that ends the run>

Return: <the report shape you want back>

Tight boundary + explicit stop condition = a fast agent that returns something you can act on. Vague brief = an agent that wanders.

Modes, Flags, Sandbox

• --force / --yolo force-allows Cursor tool calls. Use it for autonomous runs.
• --ask = read-only Q&A. --plan = planning without edits. Default agent = full build.
• --dir <path> sets the working repo. Always set it.
• --map injects docs/CODEBASE_MAP.md when present - cheap orientation for research and implementation.
• --browser-harness is a Cursor Pilot wrapper flag that injects the browser-harness skill + plugin. The plugin also exposes AgentMail from Codex's local AgentMail skill for OTP and magic-link E2E. Opt-in - only QA mode needs it. When on, the wrapper auto-disables the Cursor sandbox (browser-harness needs localhost CDP).
• --headless uses the old agent -p --output-format json launch path for scripted callers. Without it, jobs are live interactive TUI sessions.
• Interactive jobs auto-accept Cursor's workspace trust prompt for unattended runs instead of hanging at the gate.
• --dry-run prints the launch summary and prompt preview without spawning. Use it to check token cost and the assembled prompt.

Running From Codex / Claude

When you run cursor-pilot commands, run them as approved/escalated shell commands. Cursor Agent reads macOS Keychain auth, and browser-harness needs localhost CDP access. A sandboxed orchestrator command can make agent status fail with SecItemCopyMatching and can make browser-harness mis-detect Chrome.

Health Check

Run this when Cursor, tmux, model access, or browser-harness setup is suspect:

cursor-pilot health

It verifies tmux, Cursor auth, the default model, and (for QA) browser-harness files, AgentMail skill availability, the Cursor plugin, and the browser-harness executable. If health reports a Keychain sandbox error, rerun it as an approved/escalated command before dispatching work.