Use Cursor

Use Cursor

🚨 HARD RULE: NEVER dispatch cursor-agent via WSL nohup (2026-05-25)

NEVER use nohup wsl -e bash -c "cursor-agent ..." or any WSL-dispatched cursor-agent pattern.

Receipt: two parallel tracks were dispatched via nohup wsl -e bash -c "cursor-agent ...". Both agents failed to bootstrap (workspace trust dialog / env-detection). The cursor-agent processes entered an infinite pip list fanout loop. The operator discovered it 10 hours later: 189 orphaned processes consuming 71.4 GiB RSS in WSL, threatening workstation stability. Zero useful work shipped via cursor. Both tracks were orchestrator-taken-over via Agent tool sonnet subagents — which shipped the work cleanly within 45 min.

This is the 4th consecutive WSL cursor dispatch failure in a single day. The success rate is 0/4.

What to do instead:

If WSL cursor MUST be used (emergency only): wrap with timeout 1800 cursor-agent --trust -p "$PROMPT" || true, track PID in /tmp/cursor_$NAME.pid, arm cleanup: pkill -9 -f "cursor-agent.*$NAME".

Cleanup playbook (when orphans found):

wsl bash -c 'ps -ef | grep -E "pip list|cursor-agent" | grep -v grep | wc -l'  # count
wsl bash -c 'pkill -9 -f "pip list"; pkill -9 -f "cursor-agent"'                # kill

If you keep a durable-memory file for recurring tool gotchas, log this one there — it's expensive enough to re-learn twice.

🟢 TIME-BOUND: UNLIMITED TOKENS UNTIL 2026-08 — USE AGGRESSIVELY

Through 2026-08, cursor-agent in WSL on auto-model has UNLIMITED token budget on the user's subscription. This is a finite window — use it as aggressively as possible during this period. After 2026-08, the unlimited-tokens subscription expires; cursor demotes to "use sparingly like other CLIs."

Default behavior through 2026-08:

• Any task with >500 words of write-output → route to cursor, not Claude / not an opus-tier Agent
• Multi-file refactors / doc rewrites / skill updates / template population → cursor
• Long-form generation (paper sections, blog drafts, code scaffolding) → cursor
• Audit-style passes where the work product is a written report → cursor
• Anything where Claude's tokens would be "writing out" instead of "reasoning" → cursor

Don't use cursor for (even during unlimited window):

• Remote job dispatch / SSH / REST API calls (cursor can't reach our infra)
• Small targeted edits (Edit tool is faster than spec-writing for cursor)
• Reasoning that must feed back into the current Claude conversation (cursor's output is the deliverable; it can't continue the dialogue)
• Anything time-critical (cursor dispatch has 2-5 min wall time per task)

Refresh checkpoint: 2026-07 — verify subscription renewal status. If renewed → keep this guidance. If not renewing → flip this section to "demoted" mode for 2026-08+.

🛑 MANDATORY audit step after cursor (no exceptions)

Cursor's output is NEVER trusted blind. The unlimited-token window makes cursor cheap, but it also means cursor produces volume faster than it produces correctness. Every cursor dispatch is followed by an audit pass:

Why this is mandatory (encoded after 2026-05-19 observation): cursor's unlimited-tokens model spec means it will produce a complete-LOOKING artifact even when it misunderstood the spec. Without the audit pass, you ship cursor's misunderstanding as Claude's deliverable. The audit catches:

• Spec deviations (cursor implemented something close but not quite what you asked)
• Surface-level correctness (compiles / tests pass) without semantic correctness
• Missing cross-references (cursor wrote section X but didn't update sibling section Y)
• Stale citations / hallucinated paths (cursor invented file paths that don't exist)
• Tone / framing drift (cursor's voice differs from project conventions)

Don't skip the audit because cursor's output "looks fine." Looking-fine is exactly what cursor optimizes for; it's the audit's job to find what looks fine but isn't. The audit cost is trivial vs the cost of shipping cursor's misread.

The 3-stage workflow (every cursor dispatch):

1. Claude writes the spec → cursor implements (unlimited tokens)
2. Audit pass (opus Agent OR thinktank 3-seat)
3. Claude reviews audit verdict, decides ship vs revise, commits

Stage 3 stays on the Claude side — never delegate "decide ship vs revise" to the auditing model. The auditor surfaces issues; you adjudicate.

Core rule

Cursor is a bounded implementation worker. Claude owns the plan, the prompt file, the audit, the tests, the commits, and the final answer.

cursor-agent runs in WSL on auto-model with unlimited tokens (through 2026-08; see time-bound notice above). Send heavy content-write tasks (skill updates, doc rewrites, multi-file refactors) to cursor; keep planning, audit, remote job orchestration, and decisions on the Claude side.

Cursor model roster (2026-07-01 picker snapshot)

Default remains Auto (unlimited tokens through 2026-08 — leave --model off for bulk writes). Pin a --model <slug> ONLY when you need deterministic, low-chatter editing. Display names below are from the Cursor picker; confirm the exact --model slug via cursor-agent --help before pinning — the CLI slug format is lowercased-hyphenated (sonnet-5, opus-4.8, gpt-5.5), not the display string.

Deterministic-edit pin: prefer Sonnet 5 or Opus 4.8 (top Anthropic tiers, 300K + High reasoning) for clean multi-file edits; GPT-5.5 as the cross-vendor alternate. The old sonnet-4 / gpt-5 pins are now bottom-of-roster — don't use them.

⚠ Fable 5 is NOT in the Cursor picker (2026-07-01 snapshot). UPDATE 2026-07-03: Fable 5 IS available again via Claude Code — interactive /model AND headless claude -p --model claude-fable-5 (pong-verified 2026-07-03) — and listed in droid ≥0.164.0. Cursor-side status unverified since the 2026-07-01 snapshot; re-check the picker before claiming either way.

When to use vs when to skip

Don't use cursor-agent for: small targeted edits (Edit tool is faster), debugging / reasoning / remote job orchestration / SSH work / git push (Claude owns this), or anything where you need cursor's output to immediately influence your next step.

Workflow

digraph cursor_workflow {
    "Identify cursor-fittable task" -> "Verify cursor-agent in WSL";
    "Verify cursor-agent in WSL" -> "Write task spec file";
    "Write task spec file" -> "Launch cursor-agent in background";
    "Launch cursor-agent in background" -> "Continue Claude orchestration";
    "Continue Claude orchestration" -> "Wait for cursor exit";
    "Wait for cursor exit" -> "Audit diff";
    "Audit diff" -> "Run tests if applicable";
    "Run tests if applicable" -> "Claude commits";
}

1. Verify cursor-agent is available in WSL

wsl bash -lc 'which cursor-agent && cursor-agent --version'

Expected: /home/<user>/.local/bin/cursor-agent + a date-pinned version string. If missing, the user installs it via Cursor IDE settings; do not attempt to install yourself.

2. Write the task spec file in the repo

Save at <repo>/.claude/cursor_task_<short-name>.md (NOT .tmp/ — that gets gitignored on most repos and we want the spec discoverable). Spec shape:

# cursor-agent task: <one-line objective>

You are running as `cursor-agent -p -f --trust` (auto-router default model) in WSL against the
`<branch>` branch of `<repo>`. <Constraint sentence — e.g. "Do not commit
or push; the orchestrator will audit + commit.">

## Inputs (read-only)
- `<file paths>` — what cursor should read for context

## Edits required
- `<file>:<line range or section>` — what to add/change/remove, INLINE the
  exact content cursor should write where possible

## Constraints
- Do NOT git commit, git push, or run gh
- Preserve existing sections; add only — do not rewrite
- Keep line endings LF (avoid CRLF on Windows-mounted paths)
- If you find a blocker, write a `BLOCKER` line to stdout and exit non-zero

## Done criteria
- `git diff --stat` shows exactly <N> files changed, ~<M> lines added
- All listed files have the new sections in the right order
- No syntax errors (run `python -m py_compile <files>` for .py edits)

## Final report
Print: `[cursor-agent] DONE files=<list> +<lines> -<lines> ready_for_audit`
Then exit. Do NOT git add, commit, or push.

Be explicit. Cursor's auto mode is competent but interprets ambiguity liberally. Inline the exact target content where you can. If a section header doesn't exist, say "create a new H2 section titled X".

3. Launch cursor-agent in the background

CRITICAL: use setsid bash -c "..." NOT nohup ... & from inside wsl bash -c. The nohup ... & pattern silently fails with Error: No prompt provided for print mode because the positional prompt argument gets stripped during the multi-layer shell pass-through.

The working pattern (verified 2026-05-10 after nohup failed 3× with the same silent error):

wsl bash -c '
export PATH="$HOME/.local/bin:$PATH"
cd /mnt/c/path/to/repo
mkdir -p /tmp/cursor_logs
setsid bash -c "cursor-agent -p -f --trust \"Read .claude/cursor_task_<short-name>.md and implement every file specified. Run pytest if the spec requires it. Do NOT git commit. Output [cursor] DONE <short-name> when finished.\" > /tmp/cursor_logs/<short-name>.log 2>&1 < /dev/null" &
sleep 5
# the bash -c wrapper exits; the real cursor-agent process is its child:
ps aux | grep cursor-agent | grep -v grep | head -3
'

Capture the cursor-agent pid AFTER the launch (the bash -c launcher pid is short-lived; the actual cursor-agent process has a different pid):

wsl bash -c '
sleep 2
CURSOR_PID=$(ps aux | grep "cursor-agent.*--use-system-ca" | grep -v grep | awk "{print \$2}" | head -1)
echo $CURSOR_PID > /tmp/cursor_logs/<short-name>.pid
echo "cursor-agent PID: $CURSOR_PID"
'

Required flags:

• -p (--print) — non-interactive headless mode, all tools enabled
• -f (--force) — auto-approve commands; only safe because the spec forbids git commit/push and we're inside a workspace cursor controls
• --trust — trust the workspace without prompting. Required for headless mode; without it cursor refuses to write files.
• No --model flag — defaults to auto-router (unlimited tokens, the whole point of using cursor over codex)
• < /dev/null — explicit stdin redirect; without this cursor may hang waiting for a TTY in some WSL configurations
• --output-format text is the default with -p; only specify stream-json if you need to parse intermediate events

Flags that DO NOT exist (despite older docs and Claude training data):

• --auto — does not exist; auto-mode is the default
• --no-color — does not exist
• --system-prompt — does not exist
• --max-turns — does not exist (cursor decides its own loop length)

Sanity-test pattern after launch. Always verify the process is actually alive AND that the log file is being written to:

wsl bash -c '
sleep 8
ps aux | grep cursor-agent | grep -v grep | head -3
ls -la /tmp/cursor_logs/<short-name>.log
head -20 /tmp/cursor_logs/<short-name>.log
'

If the cursor-agent process is missing from ps AND the log shows "No prompt provided for print mode" → the prompt got stripped during shell pass-through. Re-launch with the setsid bash -c pattern above (NOT nohup ... &).

The Bash tool's run_in_background: true parameter is NOT a substitute for the setsid pattern — it has the same prompt-stripping problem when invoking via wsl bash -c.

4. Continue Claude orchestration

Cursor takes 5–15 minutes for typical multi-file tasks. Use that time for parallel Agent-tool subagent dispatches, background job monitoring, or your own focused work. Never tail the cursor log via cat /tmp/cursor_*.log in a hot loop — wastes tokens. Check it once at the end.

5. Wait for cursor exit, then layered audit: subagent first, you second

wsl bash -lc 'while kill -0 $(cat /tmp/cursor_<name>.pid) 2>/dev/null; do
  sleep 30; done && echo "exited"; tail -30 /tmp/cursor_<name>.log'

Layered review pattern (load-bearing — saves Claude tokens):

1. Subagent audits cursor's diff first — dispatch a feature-dev:code-reviewer Agent subagent with a prompt that says "audit the working tree diff produced by cursor-agent against the spec at .claude/cursor_task_<name>.md. Look for: scope creep, wrong-file edits, content drift from the spec, syntax errors, indentation drift, accidental regenerations of unrelated sections. Output: severity-ranked findings."
2. You audit the subagent's report + the diff — read the report (small), then check the suspicious hunks the subagent flagged. Don't re-read the whole diff. The subagent has already paid the read-cost.
3. If clean: git add the explicit files, commit, push.
4. If subagent flags issues: rewrite the cursor spec to be more explicit, relaunch cursor against the same files (cursor's auto mode is stateless across runs), re-audit.

git diff --stat               # quick shape check
git diff --name-only          # confirm scope = spec
# then dispatch subagent to audit; only read flagged hunks yourself

Diff-first, file-second. Don't read whole files; read hunks. The two-tier audit (subagent → you) means cursor's tokens write the content, the subagent's tokens read it for review, and your tokens spend on the verdict only. Three independent contexts; each does what they're cheapest at.

6. Run tests + commit

Run only the tests touching the changed files. If clean: git add the explicit files (NOT git add -A), commit with a message that credits cursor-agent ("worker: cursor-agent --auto"), push.

Prompt shape — required fields

Guardrails

• Never paste raw markdown into bash -lc "$(cat ...)". Shell expansion can execute prompt text or corrupt the task. Use a file path argument and let cursor open it.
• No backticks in the launch command's prompt string. They get evaluated by the host shell. Reference the spec file by path.
• Process pollution check after a bad launch: wsl bash -lc 'ps -ef | grep -E "cursor-agent" | grep -v grep'
• Do not pass HF_TOKEN, cloud-provider API keys, or other secrets in the prompt. Cursor reads them from .env.local if it needs them; the spec must say so.
• Cursor-environment assumptions are advisory, not authoritative. If cursor suggests downgrading a dependency or Python version because its WSL interpreter differs from the project's, verify against pyproject.toml and recent commits before applying. Cursor's WSL Python may not match the project venv.
• Windows cleanup safety: before removing .venv or generated artifacts cursor created, resolve absolute paths and confirm they are inside the workspace. Cursor sometimes creates .venv/lib64 symlinks that block Windows uv; remove only untracked artifacts.
• Do not trust cursor's success report alone. It says "DONE" optimistically. Run the diff audit + tests yourself.
• Token-conserve discipline: large cursor token usage is OK only when the task is bounded + the audit path stays diff-first. If you find yourself reading whole files cursor wrote, the task was too big — split next time.

Troubleshooting — recurring failure modes

When to escalate / abort

• Cursor exits non-zero or prints BLOCKER → read the log tail (last 30 lines), diagnose, possibly rewrite the spec + relaunch
• Cursor edits files outside "Edits required" scope → revert via git checkout -- <file>, narrow the spec
• setsid pattern fails too → check cursor-agent status for auth; if fine, fall back to codex-cli (gpt-5.5) — different infra path
• Cursor commits despite the no-commit constraint → git reset --soft HEAD~1 to keep the work, audit, then re-commit cleanly with our message
• Cursor stalls past expected wall (>20 min for typical multi-file edits) → kill $(cat /tmp/cursor_*.pid), inspect log, decide whether to retry

Real-world impact (encoded from a real orchestration session)

• Skills update across 4 project-local skill files (~250 lines added, preserving existing content): cursor-agent shipped this in ~8 min while Claude orchestrated 3 parallel Agent-tool subagents (code-reviewer audit, code-architect refactor, Exa research). Net: ~30 min of wall-clock work done in ~10 min real time, ~zero Claude output tokens spent on the skill bodies.
• Spec-precision-pays-off lesson: when the spec inlined the exact markdown to add ("add this section verbatim"), cursor produced clean diffs with no rewrites. When the spec said "rephrase this section", cursor produced 3x more diff than necessary and 2 of 4 files needed hand-touch fixes. Always inline.
• Diff-first audit caught one case where cursor inserted a section in the wrong file (it picked a heuristic match against the section title rather than the explicit file path). Spec was ambiguous on which file the new section belonged to; lesson: file paths in the spec must be unambiguous.

Red flags — STOP and rewrite the spec

• "Make this better" — cursor will rewrite, not improve
• "Fix all the bugs" — needs explicit list
• "Update the docs" — needs explicit file paths
• "Refactor for clarity" — too open-ended for auto mode
• Multi-step plans without explicit sequencing → split into N specs

Cross-references

• Sibling skills (the rest of the delegation matrix):
  • use-codex (~/.claude/skills/use-codex/SKILL.md) — peer-review + bounded write via OpenAI Codex CLI; complementary (cursor implements, codex audits).
  • use-gemini (~/.claude/skills/use-gemini/SKILL.md) — third-opinion audit via Google Gemini CLI (dead post-2026-06-18 -> use agy/droid); --approval-mode plan is inherently read-only.
  • use-claude-in-chrome (~/.claude/skills/use-claude-in-chrome/SKILL.md) — drives the user's REAL Chrome session (cookies/OAuth/MFA inherited). When cursor needs browser automation against a logged-in SaaS dashboard, dispatch via the Skill tool to use-claude-in-chrome instead (cursor-agent has no equivalent and Playwright won't share the session). Cursor itself can call mcp__claude-in-chrome__* tools if the orchestrator loads them via ToolSearch first.
• Codex equivalent (different ecosystem): ~/.agents/skills/use-cursor/SKILL.md (the source this was adapted from). Codex emphasizes the PowerShell host-shell + Windows GitHub split; Claude Code typically does git/gh in the Bash tool already and has the Agent tool for parallel subagent dispatch, so the boundary rules differ. Use whichever skill matches the host you're running on.
• For research/audit work that needs to feed back into the conversation, prefer the Claude Agent tool (subagent_type: feature-dev:code-reviewer, feature-dev:code-architect, general-purpose with mcp__Exa__*). Agent subagents return their report inline; cursor-agent commits silently and you audit the diff.