Cursor

Use the same $GTIMEOUT pattern as the Gemini and Codex skills:

GTIMEOUT="/opt/homebrew/bin/gtimeout"
test -x "$GTIMEOUT" || GTIMEOUT="/opt/homebrew/bin/timeout"
test -x "$GTIMEOUT" || { echo "gtimeout not installed (brew install coreutils)"; exit 1; }

Every template below uses $GTIMEOUT. Do not use bare timeout.

Availability Check

Before any invocation, verify the CLI is installed and authenticated:

"$AGENT" status 2>/dev/null | grep -q "Logged in" || {
  echo "Cursor Agent not authenticated — run 'agent login'"
  exit 1
}

If unavailable, skip the Cursor portion of the workflow and note "Cursor Agent unavailable" in output.

Concurrency Limit (MANDATORY)

Cursor Agent supports a maximum of 3 simultaneous headless processes. Exceeding this causes API rate limiting and degraded responses. Track active sessions via a PID file (same pattern as Codex/Gemini):

PID_FILE=/tmp/cursor-slots.pid

# Prune dead entries
if [ -f "$PID_FILE" ]; then
  while IFS= read -r pid; do
    ps -p "$pid" >/dev/null 2>&1 && echo "$pid"
  done < "$PID_FILE" > "${PID_FILE}.tmp"
  mv "${PID_FILE}.tmp" "$PID_FILE"
fi

# Check slot availability
ACTIVE=$(wc -l < "$PID_FILE" 2>/dev/null || echo 0)
if [ "$ACTIVE" -ge 3 ]; then
  echo "All 3 Cursor Agent slots occupied — queuing"
fi

After launching in the background, append its PID:

echo $! >> /tmp/cursor-slots.pid

Headless Mode Essentials

Cursor Agent headless mode requires -p (print) flag. Without it, the CLI enters interactive TUI mode which hangs in subshells.

Key flags for headless:

Do not treat --force as a write barrier. On the current CLI build, plain -p can still modify files, and --mode ask / --mode plan are not reliably read-only in practice. When the main worktree must stay untouched, run in an isolated worktree or disposable copy.

To capture output in a file, redirect stdout: > OUTPUT_FILE.

Model Selection

Current account has access to these models (use agent models to refresh):

Routing by Task Type

Execution Modes

Agent Mode (default) — Full Tool Access

The default mode. Agent can read files, write files, run shell commands, and use all configured MCP tools. Use --force to allow writes without confirmation.

$GTIMEOUT 120 "$AGENT" -p --trust --force --workspace /path/to/project \
  "PROMPT" 2>/dev/null

Ask Mode — Q&A / Analysis

Use for analysis and understanding tasks. The CLI help describes this as read-only, but the current build has been observed to modify files anyway, so do not trust it as a safety boundary.

$GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
  "PROMPT" 2>/dev/null

Plan Mode — Planning / Analysis

Use when you want planning-oriented responses. The CLI help describes this as read-only, but the current build has been observed to modify files anyway, so do not treat it as a guaranteed dry run.

$GTIMEOUT 120 "$AGENT" -p --trust --mode plan --workspace /path/to/project \
  "PROMPT" 2>/dev/null

Task-Type Templates

Every template below includes --trust — required for headless mode to avoid interactive workspace trust prompts.

Code Review (Analysis; isolate if repo must stay clean)

RESULT=$($GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
  "Review this codebase for security issues, focusing on input validation and auth." 2>/dev/null)
echo "$RESULT" > OUTPUT_FILE

For git repos where analysis must not touch the main tree, prefer:

$GTIMEOUT 120 "$AGENT" -p --trust --mode ask -w review-pass \
  --workspace /path/to/project \
  "Review this codebase for security issues, focusing on input validation and auth." \
  2>/dev/null > OUTPUT_FILE

Code Generation (Write)

$GTIMEOUT 120 "$AGENT" -p --trust --force --workspace /path/to/project \
  "Add input validation to all API route handlers" 2>/dev/null

Structured JSON Output

Use --output-format json for machine-parseable results:

$GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
  --output-format json "Analyze the test coverage gaps" 2>/dev/null

JSON output shape:

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 3723,
  "result": "...",
  "session_id": "...",
  "usage": { "inputTokens": 3, "outputTokens": 23, ... }
}

Extract the result with: jq -r '.result'

Long Prompt via File

For prompts too long for a shell argument, put the prompt in a file and reference it:

$GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
  "$(cat /path/to/prompt.md)" 2>/dev/null > OUTPUT_FILE

With Model Override

$GTIMEOUT 120 "$AGENT" -p --trust --force --model sonnet-4.6-thinking \
  --workspace /path/to/project "PROMPT" 2>/dev/null

Parallel Execution (Background)

$GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
  "$(cat /tmp/review-prompt.md)" 2>/dev/null > /tmp/cursor-review-output.md &
echo $! >> /tmp/cursor-slots.pid
CURSOR_PID=$!
# ... launch other reviews ...
wait $CURSOR_PID

Isolated Worktree (Git Projects)

Cursor can spin up an isolated git worktree so headless writes don't collide with the main working tree:

$GTIMEOUT 300 "$AGENT" -p --trust --force -w headless-task \
  --workspace /path/to/project "Implement feature X" 2>/dev/null

The worktree is created at ~/.cursor/worktrees/<reponame>/headless-task. Use --worktree-base main to base it on a specific branch.

Resume a Session

# Resume by session ID
$GTIMEOUT 120 "$AGENT" -p --trust --resume SESSION_ID \
  "Continue where you left off" 2>/dev/null

# Resume the most recent session
$GTIMEOUT 120 "$AGENT" -p --trust --continue \
  "Continue where you left off" 2>/dev/null

MCP Server Access

Cursor Agent loads MCP servers from .cursor/mcp.json in the workspace. In headless mode, use --approve-mcps to auto-approve server connections:

$GTIMEOUT 120 "$AGENT" -p --trust --force --approve-mcps \
  --workspace /path/to/project "PROMPT" 2>/dev/null

To inspect configured MCPs:

"$AGENT" mcp list
"$AGENT" mcp list-tools SERVER_NAME

Output Validation (MANDATORY)

Same discipline as Codex and Gemini — validate by character count, not lines:

CHARS=$(wc -c < OUTPUT_FILE 2>/dev/null | tr -d ' ')
if [ "${CHARS:-0}" -lt 50 ]; then
  echo "Cursor output too small (${CHARS} chars) — likely failed"
fi

For JSON output, also validate the structure:

IS_ERROR=$(jq -r '.is_error // false' < OUTPUT_FILE 2>/dev/null)
if [ "$IS_ERROR" = "true" ]; then
  echo "Cursor returned an error"
fi

For analysis tasks against a non-disposable git checkout, detect unexpected mutations after the run:

BEFORE=$(git -C /path/to/project status --porcelain 2>/dev/null || true)
# ... run Cursor analysis task ...
AFTER=$(git -C /path/to/project status --porcelain 2>/dev/null || true)
if [ "$AFTER" != "$BEFORE" ]; then
  echo "Cursor modified the tree during analysis — inspect diff before continuing"
fi

Critical Gotchas

1. -p is mandatory for headless — without it, the CLI enters interactive TUI mode and hangs indefinitely in subshells. Every headless call MUST include -p.

2. --trust is mandatory for headless — without it, the CLI prompts for workspace trust interactively and hangs.

3. --force is not a write gate on the current CLI — on the 2026.03.11-6dfa30c build, plain -p wrote files in disposable tests. Use --force for unattended command/tool execution, but do not rely on omitting it to protect the workspace.

4. --mode ask and --mode plan are not reliably read-only — despite the CLI help text, both modes wrote files in disposable tests on 2026-03-13. Use isolated worktrees or disposable copies when analysis must be non-destructive.

5. Always wrap with $GTIMEOUT — the CLI can hang on network issues, large codebases, or MCP server failures. 120s for reviews, 180s for generation, 300s for large refactors.

6. 2>/dev/null is mandatory — stderr contains ANSI escape codes, progress indicators, and MCP startup logs that corrupt output and inflate context.

7. JSON output is a single object, not JSONL — unlike Codex, Cursor's --output-format json returns one JSON object with a .result field. Use jq -r '.result' to extract.

8. Prompts are positional — the prompt is the last argument after all flags. Putting flags after the prompt string causes parse errors.

9. Model defaults to account setting — currently opus-4.6-thinking. Override with --model <id> when a cheaper or faster model suffices.

10. Worktrees require a git repo — -w fails silently in non-git directories. Only use for git-tracked projects.

11. There is no -o output flag on the current CLI — agent -p ... -o file exits 1 with no stderr. Capture output with stdout redirection instead: "$AGENT" -p ... > OUTPUT_FILE or --output-format json > OUTPUT_FILE.

12. Session resume requires the session ID — get it from JSON output's session_id field, or use agent ls to list recent sessions.

Flag Reference

Fallback Behavior

Examples

Skill (counter-review): Needs Cursor to review project for completeness issues.
--> RESULT=$($GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
      "Scan for stubs, TODOs, placeholder values, empty catch blocks, and functions with no real implementation. Report each with file path and line number." 2>/dev/null)
    echo "$RESULT" > /tmp/cursor-completeness-review.md

Skill (meta-review): Firing Cursor alongside Codex and Gemini in parallel.
--> $GTIMEOUT 120 "$AGENT" -p --trust --mode ask --workspace /path/to/project \
      "$(cat /tmp/review-prompt.md)" 2>/dev/null > /tmp/cursor-review-output.md &
    echo $! >> /tmp/cursor-slots.pid
    CURSOR_PID=$!
    # ... launch other reviews ...
    wait $CURSOR_PID

Skill (meta-execute): Cursor writes code in an isolated worktree.
--> $GTIMEOUT 300 "$AGENT" -p --trust --force -w wu-3-auth \
      --model sonnet-4.6-thinking --workspace /path/to/project \
      "Implement JWT refresh token rotation per the spec in project-plan.md WU-3" 2>/dev/null

Skill (quick analysis): Fast analysis pass with a cheap model.
--> $GTIMEOUT 60 "$AGENT" -p --trust --mode ask --model sonnet-4.6 \
      --workspace /path/to/project \
      "List all exported functions in src/api/ that lack input validation" 2>/dev/null

Before completing, read and follow ../references/cross-cutting-rules.md.