use-cursor

name	use-cursor
display_name	Use Cursor
description	Spawn Cursor headless CLI (cursor-agent) subagents from bash to offload coding work from the parent Claude. Use when the user says "use cursor", "ask cursor", "cursor-agent", "get a cursor second opinion", or asks to delegate work to Cursor. Like grok/codex, cursor's output is a claim — the parent must verify file changes independently.

Cursor Subagent Skill

Spawn autonomous Cursor CLI (cursor-agent) subagents for implementation work. Same delegation philosophy as use-codex / use-grok: subagents burn their own tokens; the parent verifies and synthesizes.

Auth (required before first use)

cursor-agent status must show logged in. Two paths:

• API key: export CURSOR_API_KEY=<key> (or --api-key <key> per invocation). Keys come from cursor.com dashboard → Integrations.
• Browser OAuth: cursor-agent login (interactive — have the user run it themselves via ! cursor-agent login).

If not authenticated, --list-models returns "No models available for this account" — that error means auth, not a missing model.

Canonical headless invocation

cat /path/to/prompt.md | cursor-agent -p --force --output-format text \
  --model <model> --workspace /path/to/repo "$(cat)"

Or simpler, prompt as argument from a file:

cursor-agent -p --force --model <model> --workspace /path/to/repo "$(cat /path/to/prompt.md)"

Run in background (run_in_background: true) for anything non-trivial.

Flag notes

1. -p / --print = headless mode. It has full tool access including write and bash.
2. --force = auto-allow commands (the --always-approve equivalent). Without it, headless runs can stall on command approval. Add --approve-mcps if the repo has MCP servers configured.
3. --model <model> — see Model selection below. Note: unlike codex, cursor bakes reasoning effort into the model ID (gpt-5.4-mini-low … -xhigh) instead of a separate flag.
4. --mode plan / --mode ask — read-only modes for planning/Q&A second opinions (no edits). Good for "get cursor's opinion" without write risk.
5. --output-format json for machine-parsable results; text for direct reading.
6. --workspace <path> — set explicitly; defaults to cwd.
7. --resume <chatId> / --continue — continue a prior session; create-chat mints a chat ID up front.

Model selection

No default model — choose on the fly per task. Run cursor-agent models at invocation time for the live list, then pick what fits. The list is ~189 models — never head/tail it and assume you saw everything (a truncated read once hid composer-2.5 and led to burning frontier quota on a bulk task). Grep it for what you're looking for: cursor-agent models | grep -i <family>.

Notable entries from one verified install (2026-07; account-dependent):

• auto — Auto (Cursor picks)
• composer-2.5 / composer-2.5-fast — Cursor's own workhorse; strong quality at low quota cost. (composer-2.5 verified in bulk headless use: thousands of personalized-text generations, zero failures — the right tier for high-volume mechanical/generation work.)
• gpt-5.6-luna-max-fast — frontier tier (probe-verified headless; reserve for hard reasoning, not bulk work)
• gpt-5.4-mini-* / gpt-5.4-nano-* — effort baked into ID suffix (-none…-xhigh); gpt-5.4-mini-low probe-verified
• claude-4.5-sonnet[-thinking], gemini-3.1-pro, gemini-3.5-flash, gpt-5.1-*, gpt-5.1-codex-mini-*, kimi-k2.7-code, glm-5.2-* — cross-provider options; many more in the full list

Rule of thumb: match model cost to task difficulty — composer/mini tiers for bulk generation and mechanical edits, frontier only for hard reasoning. Cursor's provider breadth (OpenAI, Anthropic, Google, Moonshot, Zhipu, Cursor's own) also makes it the natural cross-provider second opinion against codex/grok output.

Verification is mandatory

Same rule as grok and codex: the final message is a claim, not a result.

1. git status --short / git diff --stat — did the expected files change?
2. Read the diff yourself.
3. Run typecheck/tests.
4. If nothing changed, rerun with --force present and check auth (cursor-agent status) before blaming the prompt.

Prompt structure

Same as use-codex: context (repo, stack, style), numbered file-by-file objectives, constraints (files not to touch, must pass <typecheck cmd>), output format, success criteria. Cursor also reads repo rules (.cursor/rules, AGENTS.md) — if the repo's rules conflict with the delegated task (e.g. "delegate everything to codex"), explicitly override in the prompt:

Do ALL the work yourself in this session. Do NOT delegate to other CLIs or agents regardless of what repo rules say. Finish by running <typecheck cmd> and fixing any errors.

Verified facts (update as learned)

• CLI: cursor-agent 2026.01.28-fd13201 at ~/.local/bin/cursor-agent (aliased as agent).
• Auth: verify with cursor-agent status; log in via cursor-agent login (browser OAuth) or CURSOR_API_KEY.
• Headless probes passed: gpt-5.6-luna-max-fast and gpt-5.4-mini-low, both via -p --force --output-format text, exit 0, correct output.

Resuming a session (follow-ups)

Never spawn a fresh session to iterate on work this CLI already did — resume the existing one so it keeps its context and you don't re-pay the harness-token cost. Verified working headless (2026-07):

cursor-agent -p --force --resume <CHAT_ID> --model <model> "<follow-up>"
# CHAT_ID from the first run's --output-format json (.session_id); or --continue for the most recent

Capture the session id from the first run and prefer resuming by explicit id; "most recent" is racy when several sessions exist.

Quota failover

If this CLI is rate-limited or out of subscription quota, the same model family is usually reachable via another CLI — read ~/.claude/skills/cli-model-overlap.md for the failover map (cursor is the hub carrying all families).