cursor-agent (headless)

cursor-agent -p runs Cursor's coding agent non-interactively (headless print mode): one prompt in, the agent works autonomously, output to stdout. It is a separate coding agent from you — useful as an independent implementer, reviewer, or second opinion. Treat it like delegating to a capable peer in another terminal.

Verify it is available and authenticated before relying on it:

cursor-agent --version          # e.g. 2026.05.28-a70ca7c
cursor-agent status             # "Logged in as ..." — else run `cursor-agent login`

Auth can also come from CURSOR_API_KEY or --api-key <key>. If missing, tell the user — do not silently do the work yourself without saying so.

Core invocation

# Headless: -p / --print is REQUIRED for non-interactive use.
# --trust is needed for the agent to act in the dir (safe here: ask can't write).
cursor-agent -p --trust --mode ask "summarize what this repo does"

# Pick output format and model
cursor-agent -p --trust --mode ask "explain the auth flow" --output-format text --model composer-2.5

The prompt is a positional argument. Without -p, cursor-agent launches its interactive TUI — always pass -p when scripting. The directory must be trusted (--trust) for the agent to do anything — even read-only ask runs.

Safety & permissions — read this first

Critical difference from codex: cursor-agent has no hard OS-level read-only sandbox like codex's -s read-only. In -p mode the agent "has access to all tools, including write and shell" by default. Read-only is controlled by mode, and the two modes are NOT equally safe (verified empirically):

So: for a true read-only run, use --mode ask (or run in a disposable worktree). Do not rely on --plan to prevent edits.

Trust & approvals (these gate whether it can act, not the mode's read/write nature):

Note --trust/--yolo do not turn ask into a writer — ask stayed read-only in every test. But combining --trust with --plan does let plan's soft mode make edits. Default to --mode ask for analysis; for write tasks use default mode with --trust, and tell the user.

⚠️ stdin is ignored. Unlike codex, cursor-agent does not read a piped diff or file from stdin (git diff | cursor-agent -p "review this" → it sees nothing). Verified: it replied NO_STDIN_RECEIVED. Put context in the prompt, use $(...) substitution, or have the agent run the command itself (e.g. "run git diff").

Key flags

Workflows

1. Second opinion / pair programming

Get an independent take without letting it touch files — use --mode ask.

cursor-agent -p --trust --mode ask "We're choosing optimistic locking vs a queue for X. Trade-offs?"

# Cross-check a bug hypothesis (let the agent read the files itself)
cursor-agent -p --trust --mode ask "Why might test/worker.test.ts be flaky? Inspect src/worker.ts."

Use this to challenge your own conclusion, then reconcile the two answers for the user — calling out where they agree or diverge.

2. Planning

Cursor has a plan mode that investigates and proposes an implementation plan. It's planning-focused but only soft read-only (it can still edit if pushed — see Safety), so use it to get a plan, not as a write guard.

cursor-agent -p --trust --plan "Plan how to add OAuth login: files to touch, ordered steps, risks, tests. Do not edit anything."

If you need a hard guarantee it won't touch files while planning, use --mode ask instead of --plan (ask has no write tools) and just ask it to produce the plan.

Plan-as-second-opinion: have cursor plan independently and reconcile with your own. Plan→execute: feed the plan into a fresh write-enabled run (don't rely on resume to flip modes):

cursor-agent -p --trust "Implement this plan step by step: $(cat plan.md)"

3. Code review

There's no dedicated review subcommand. Use --mode ask (reliably read-only) and have the agent inspect the diff itself — it can run git diff in ask mode. Remember stdin is ignored, so tell it to run git rather than piping the diff in:

cursor-agent -p --trust --mode ask "Review the uncommitted changes for correctness bugs and risky edge cases. Run git diff yourself. Reference file:line and quote each buggy line."

# Or against a base branch:
cursor-agent -p --trust --mode ask "Review the diff between HEAD and origin/main. Run the git command yourself. Flag bugs by file:line."

Verified: on a repo with a planted operator bug + an unguarded division, composer-2.5 in ask mode ran git diff and reported both, with a file:line table. Relay findings to the user; offer to fix, but don't auto-apply unless asked.

4. Delegated implementation (headless)

Hand off a self-contained task. Needs --trust (and --yolo if it must run build/ test commands unattended).

cursor-agent -p --trust "Add input validation to the /signup handler and a unit test for it."

Then review what it changed (git diff) before trusting it — inspect it like any other diff. For risky tasks, isolate the changes in a worktree (workflow 7).

5. Structured / scriptable output

--output-format json emits a single final result object you can parse:

cursor-agent -p --trust --mode ask "One-line summary of this repo" --output-format json | jq -r .result

The JSON object includes result (the answer), session_id, and usage. Verified: jq -r .result cleanly extracts just the answer.

6. Multi-turn (resume / continue)

Continue a prior session with its context retained.

cursor-agent -p --continue "now also add the migration"
cursor-agent -p --resume <chatId> "address the review comments"
cursor-agent ls                 # list resumable sessions
ID=$(cursor-agent create-chat)  # pre-create a session id for scripting

7. Isolated / parallel work (git worktree)

Run a delegated task in a separate worktree so it never touches your working tree — ideal for background or parallel work.

cursor-agent -p --trust -w feature-x "Implement feature X end to end."
# Lands in ~/.cursor/worktrees/<repo>/feature-x ; review and merge when done.

For long tasks, launch it in the background (in this harness, run_in_background: true) and capture output to a file.

8. Headless parallel fan-out (one agent spawns many)

cursor-agent -p can spawn child cursor-agent -p processes and run them in parallel — either you script the loop, or a --force parent does it through its own shell tool (in -p it "has access to all tools, including write and shell"). There is no native fan-out/join subcommand and no recursion guard (CURSOR_AGENT=1 is set in children but nothing blocks on it — verified nesting runs fine), so you hand-roll it. The canonical pattern:

# One worktree per child (no write collisions) + --force (headless approval) + json (mergeable)
for task in A B C; do
  ( cursor-agent -p --force -w "wt-$task" \
      "<fully self-contained prompt — stdin is ignored, inline ALL context>" \
      --output-format json > "out-$task.json" 2>&1 ) &
done
wait        # MANDATORY — see trap 3
# merge: read out-*.json (.result, .usage), then `git -C <worktree>` to collect edits

Verified empirically: 3 children in separate worktrees ran truly concurrently (~37s wall, staggered finishes, each worktree held only its own edit, main tree untouched); 6 concurrent ask children = 6/6 success, no rate-limiting; a single --force parent, told to isolate per-child, autonomously created the right worktrees and captured each child's stdout. Three silent failure modes — each produces no error, just wrong/empty results:

1. No --force → children never run. In -p there's no human to approve the spawn command, so the parent's shell calls are rejected outright. --force/ --yolo is mandatory for the parent. (Verified: without it, "every attempt to execute it via the Shell tool was rejected.")
2. Shared tree → silent lost update. Two concurrent writers on the same file with no worktree → one edit silently vanished (no error, no index.lock). Give every child its own -w/--worktree; isolation was perfect in every test.
3. & without wait → orphaned children. If the parent shell exits before the children finish, they die mid-flight and make no edits. Always wait (or nohup/disown for true fire-and-forget). (Verified: the parent's first attempts lost their children exactly this way until it added wait.)

Auth rides on the on-disk login (no CURSOR_API_KEY needed locally; set it for CI); --trust is sticky per-dir so children inherit it. Latency stacks ~20-30s per nesting layer, so keep nests shallow. Tell the agent to isolate explicitly — it self-isolates correctly when instructed but won't reliably infer it; for determinism, script the loop yourself rather than asking one -p agent to orchestrate.

Output / event format

• --output-format text → just the final answer text.
• --output-format json → one final object: {"type":"result","result":"...","session_id":"...","usage":{...}}. Extract the answer with | jq -r .result.
• --output-format stream-json → NDJSON event stream (verified types): system (init: model, cwd, permissionMode), user, assistant, text/word (incremental text), tool_call (one per file edit / shell command), connection/ retry (network-drop recovery, with attempt counter), then result. Add --stream-partial-output for finer text deltas.

# Watch progress as a stream
cursor-agent -p "build the feature" --trust --output-format stream-json

Monitoring a running instance (liveness)

Tell a backgrounded / orchestrator-owned run's state apart — finished, still working, or wedged — without killing anything. All checks are read-only.

pgrep -fl cursor-agent                           # alive? (also matches wrapper shells of other runs)
ls -l out.txt                                    # the redirected-stdout file
find ~/.cursor/chats -type f -mmin -2            # session store (store.db-wal) touched = an agent is working
find ~/.cursor/projects/*/agent-transcripts -name '*.jsonl' -mmin -2   # transcript appended during multi-step runs

• Finished: process gone + stdout file non-empty. ⚠️ With --output-format text the file stays 0 bytes until the very end (verified) — file growth is a progress signal only with stream-json, which appends events every few seconds mid-run (verified).
• Still working: process alive + a file under ~/.cursor/chats/<hash>/<chat-id>/ or ~/.cursor/projects/<cwd-slug>/agent-transcripts/<id>/<id>.jsonl fresh within ~2 min. Both dirs are shared by all runs — match <cwd-slug> (the run's cwd with /→-, e.g. Users-payne-Github-myrepo) to your run before trusting it.
• Wedged: process alive but its session files untouched for 10+ min (heuristic). On slow networks a turn can legitimately take minutes — check twice before judging.
• Network drops (verified by cutting the connection mid-stream): it reconnects with exponential backoff and resumes cleanly when the network returns (15 s outage → exit 0, intact answer); if it never returns, it gives up after ~10 attempts / ~7 min with exit 1 and Connection failed repeatedly on stderr — it does not wedge. In stream-json, each attempt is visible as a {"type":"connection","subtype":"reconnecting","attempt":N} + {"type":"retry"} event pair, so a watcher can tell "retrying" from "dead".

Context files

Cursor reads AGENTS.md and .cursor/rules/* for project/user conventions. For a one-off run that should follow specific rules without editing those files, put the rules directly in the prompt. cursor-agent generate-rule scaffolds a new rule.

Gotchas

• No hard read-only sandbox. Unlike codex's -s read-only, safety is by mode. --mode ask is reliably read-only (no write tools); --plan is only soft read-only and wrote 2/4 times when pushed — don't trust it as a write guard.
• stdin is ignored — piping git diff in does nothing. Embed context in the prompt or have the agent run the command itself.
• Untrusted dirs refuse to act — pass --trust (trust persists per-dir). --trust/--yolo don't make ask write, but they do let --plan edit.
• -p is mandatory for scripting — without it you get the interactive TUI.
• Review before trusting writes — inspect git diff; consider -w worktree isolation for risky tasks.
• It's a different model (Cursor's Composer by default, or --model sonnet-4/ gpt-5/etc.) — when used as a second opinion, surface both views rather than assuming cursor is right.
• Don't leak secrets into prompts sent to an external model.
• Parallel fan-out has three silent traps (see workflow 8): no --force → children silently never run; shared tree → silent lost-update (use one -w worktree per child); & without wait → parent exit orphans the children.