| name | use-cursor |
| description | Use when delegating bounded coding work to cursor-agent (in WSL, auto-mode, unlimited tokens) to conserve Claude tokens for orchestration + audit — multi-file edits over an explicit task spec where the work is bounded, auditable diff-first, and an Agent-tool subagent's tokens would otherwise be wasted on writing-out-content. |
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:
| Need | Wrong | Right |
|---|
| Long bulk-code-writing job | nohup wsl -e bash -c "cursor-agent --trust -p ..." | Agent tool, subagent_type: general-purpose, model: sonnet, bounded task in prompt |
| Multi-file refactor | WSL cursor dispatch | Sonnet subagent (proven: 8/8 shipping ratio on 2026-05-24 via Agent tool) |
| "Unlimited tokens" appeal | WSL cursor | Sonnet Agent — Claude Code's per-task cost is far lower than the WSL ops overhead per failed dispatch |
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'
wsl bash -c 'pkill -9 -f "pip list"; pkill -9 -f "cursor-agent"'
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:
| Cursor output stakes | Audit pattern |
|---|
| Routine (skill update, doc rewrite, single-domain refactor) | opus-tier Agent audit — dispatch general-purpose or feature-dev:code-reviewer at model: opus against the diff cursor produced. Audit prompt: "review the diff cursor produced against the original task spec; surface any bugs, deviations from spec, or correctness issues." Fast, low overhead. |
| High-stakes (paper-grade, public-ship, money-touching diff) | multi-model audit panel — dispatch a 3-way pattern (Claude + codex + gemini) against the cursor output. Pass the audit question verbatim, as you'd ask a human, no rephrasing. |
| Cross-domain or methodology-touching | wider audit panel — a multi-seat panel with a structured multi-dimension scoring rubric. Use when cursor wrote anything that ends up in a paper/spec doc or affects methodology rules. |
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):
- Claude writes the spec → cursor implements (unlimited tokens)
- Audit pass (opus Agent OR thinktank 3-seat)
- 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.
| Vendor | Models (display name · ctx · reasoning) |
|---|
| Anthropic | Opus 4.8 (300K, High) · Sonnet 5 (300K, High) · Opus 4.7 (300K, Extra High) · Sonnet 4.6 (200K) · Opus 4.6 (200K, High) · Opus 4.5 · Haiku 4.5 · Sonnet 4.5 · Sonnet 4 (No Thinking) |
| OpenAI | GPT-5.5 (272K) · GPT-5.4 (272K) · GPT-5.4 Mini · GPT-5.4 Nano · GPT-5.2 · GPT-5.1 · GPT-5 Mini · Codex 5.3 · Codex 5.2 · Codex 5.1 Max · Codex 5.1 Mini |
| Cursor native | Composer 2.5 (Fast) |
| Google | Gemini 3.1 Pro · Gemini 3 Flash · Gemini 3.5 Flash |
| xAI | Grok Build 0.1 (200K) · Grok 4.3 (200K) |
| China | Kimi K2.5 · GLM 5.2 (High) |
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
| Use cursor-agent | Use Claude Agent tool subagent |
|---|
| Multi-file content writes following an explicit spec | Reasoning that needs to feed back into THIS conversation |
| Bulk-edit existing files preserving structure | Research synthesis where Claude must read the report |
| Skill updates / doc rewrites / template population | Code review (subagents have richer code-grep context) |
| Generation of boilerplate guided by examples | Tasks where Claude needs to inspect the result mid-flight |
| ≥3 files of writes; saves Claude output tokens | <3 files, fast turnaround, Claude bandwidth available |
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):
- 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."
- 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.
- If clean:
git add the explicit files, commit, push.
- 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
git diff --name-only
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
| Field | Why |
|---|
| Objective (one sentence) | Tells cursor what good looks like |
| Branch + repo path | Cursor cd's there; missing this = wrong worktree |
| Inputs (read-only) | Stops cursor from rewriting files outside scope |
| Edits required, INLINE content | Cursor's auto-mode hallucinates less when given content verbatim |
| Constraints (no commit/push, line endings, blockers) | Bounds the blast radius |
| Done criteria (file count, line count delta) | Audit anchor |
| Final report line | Signals exit cleanly |
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
| Symptom | Root cause | Fix |
|---|
Log says Error: No prompt provided for print mode; cursor-agent process not in ps | nohup cursor-agent -p ... & from inside wsl bash -c strips the positional prompt arg | Use setsid bash -c "cursor-agent ... "PROMPT" ..." pattern. Quote the prompt INSIDE the inner subshell. |
| Cursor exits immediately, empty log | Missing --trust flag in headless mode | Always include --trust when using -p. |
| Cursor hangs forever, no log output | Waiting for TTY/stdin | Add < /dev/null to the launch command. |
| Cursor refuses to write to specific paths | Workspace boundary | Pass --workspace /mnt/c/abs/path or cd before launch (use absolute paths inside the prompt). |
| Cursor opens browser / fails auth | Stale session | Run cursor-agent status first. If unauthed, the user runs cursor-agent login (Claude cannot do this — interactive browser flow). |
| Cursor produces unrelated edits | Auto-router model picked a chatty model | Pin a current top model — --model sonnet-5 or --model opus-4.8 (or --model gpt-5.5) — for more deterministic editing; confirm the exact slug via cursor-agent --help. The old sonnet-4 / gpt-5 pins are now bottom-of-roster. |
| "auto" or "--auto" flag rejected | Older docs only; flag does not exist | Just omit --model; auto-router is the default. |
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.
