# Use Cursor

> 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.

- Skill: `oimiragieo/use-cursor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/use-cursor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/use-cursor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/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:**

| 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):**
```bash
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:

| 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):
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.

| 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

```dot
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

```bash
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:

```markdown
# 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):

```bash
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):

```bash
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:

```bash
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

```bash
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.

```bash
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

| 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.