---
name: cursor-agent
description: "Delegate coding to Cursor Agent CLI (agent -p 'prompt'). Cursor Agent is a headless CLI agent with access to GPT-5.5, Claude Opus 4.7, Sonnet 4.6, and 90+ model variants through the user's Cursor subscription."
version: 1.2.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [Coding-Agent, Cursor, Autonomous, CLI]
    related_skills: [opencode, claude-code, codex]
---

# Cursor Agent CLI

Use [Cursor Agent](https://cursor.com) as an autonomous coding worker orchestrated by Hermes terminal/process tools. Cursor Agent is a headless CLI that gives access to all Cursor subscription models (GPT-5.x, Claude Opus/Sonnet, Gemini, Grok, Kimi, etc.) with configurable reasoning/speed levels.

## Installation

The `agent` CLI is installed via:
```bash
curl -fsS https://cursor.com/install | bash
```

Installed to `~/.local/bin/agent`. Check status:
```bash
agent status     # Shows login email and plan
agent --version  # Shows build date (e.g. 2026.05.16-0338208)
```

Login:
```bash
agent login
```

**Note:** Installs as `agent`, not `cursor`. The binary is at `~/.local/bin/agent`.

## Usage

### One-Shot Tasks (Non-Interactive)

```bash
agent -p "Refactor auth module and run tests" --model claude-opus-4-7-thinking-xhigh
```

### Read-Only Code Review (Findings → Manual Fix)

Use `--mode ask` to get Cursor's strongest model to perform a thorough read-only audit without making any changes. This is ideal for a final external review layer — Cursor finds issues, you fix them manually with safe patches.

```bash
agent -p "Read-only audit of this project for [scope]: ..." \
  --model claude-opus-4-7-thinking-max \
  --mode ask \
  --workspace /path/to/project \
  --trust
```

**Key constraint:** `--mode ask` prevents Cursor from editing files, running tests, or committing. Output findings, then fix Critical/High manually and verify independently. See `references/code-review-pipeline.md` for the complete workflow pattern.

### Key Flags

| Flag | Description |
|------|-------------|
| `-p, --print` | Non-interactive mode (prints response to stdout) |
| `--model <id>` | Model to use (see `agent models`) |
| `--mode plan` | Read-only planning mode (no edits) |
| `--mode ask` | Q&A mode — read-only, no file edits or execution |
| `--workspace <path>` | Working directory |
| `-w, --worktree [name]` | Isolated git worktree |
| `--trust` | Trust workspace without prompt |
| `--list-models` | List available models |
| `--resume [chatId]` | Resume a session |

### Model Selection

Cursor offers 90+ model variants. Key models:

| Model ID | Description |
|----------|-------------|
| `claude-opus-4-7-thinking-max` | Opus 4.7 1M Max Thinking — best for final review |
| `claude-opus-4-7-thinking-xhigh` | Opus 4.7 1M Extra High Thinking |
| `claude-4.6-opus-max-thinking` | Opus 4.6 1M Max Thinking |
| `gpt-5.5-extra-high` | GPT-5.5 1M Extra High |
| `gpt-5.3-codex` | Codex 5.3 |
| `gpt-5.3-codex-xhigh` | Codex 5.3 Extra High |
| `gemini-3.1-pro` | Gemini 3.1 Pro |
| `gemini-3-flash` | Gemini 3 Flash |
| `kimi-k2.5` | Kimi K2.5 |
| `grok-4.3` | Grok 4.3 1M |

Speed variants add `-fast` suffix (e.g. `gpt-5.5-extra-high-fast`). Reasoning models add `-thinking` suffix.

### From Hermes

Use `terminal()` or `delegate_task()`:

```bash
terminal(command="agent -p 'Add rate limiting to API' --model claude-opus-4-7-thinking-xhigh --workspace ~/project", timeout=300)
```

For long-running tasks, use background mode with notify_on_complete:

```bash
terminal(command="agent -p 'Implement OAuth flow' --model gpt-5.3-codex-xhigh --workspace ~/project", background=true, notify_on_complete=true)
```

### Session Management

```bash
agent ls                          # List sessions
agent resume <id>                 # Resume session
agent --continue                  # Continue last session
```

### Models List

```bash
agent models                      # All available models
agent models | grep "claude"      # Filter by model family
agent models | grep "thinking"    # Reasoning models only
```

Full model reference (tested, with speed tiers and recommendations): `references/models.md`.

## When to Delegate vs Fix Yourself

**Delegate to Cursor (`agent -p`)** when:
- Fixing 5+ compile errors across multiple files, especially API surface mismatches (Compose versions, library renames)
- Doing project-wide audits (code review, security review, architecture review)
- The user explicitly says "pass it to Cursor" or "don't do it yourself"
- You've tried a fix and made things worse — stop, delegate, don't dig deeper
- The task requires reading 20+ files to understand context before editing

**Fix yourself (patch/terminal)** when:
- It's 1-2 isolated errors with an obvious one-line fix
- It's a simple import addition or typo correction you're certain about
- The user explicitly asks you to fix something directly

**Critical rule:** Do NOT attempt batch sed/Python fixes across multiple files for API surface changes (e.g., converting `Surface(color = X)` → tv-material3 syntax). These APIs differ per calling context (clickable vs decorative, different overloads) and regex-based replacement reliably breaks things. Delegate these to Cursor.

**Post-audit rule:** When Cursor returns an audit with findings, deliver the findings to the user and WAIT. Do not start fixing anything until the user gives explicit direction. The user may want to review, prioritize, or redirect before any code changes.

## Pitfalls

1. **Never DIY batch compile-error fixes across unfamiliar API surfaces.** sed/Python-based fixes for things like tv-material3 Surface API mismatches, key handler imports, or Border type clashes will break more than they fix. The user's explicit instruction: "pass it on to cursor to fix dont do it yourself you keep breaking things." Delegate complex fixes to Cursor Opus Thinking Max.

2. **`--mode ask` prevents all file edits, test runs, and commits.** When you need a read-only review, this is the feature — Cursor outputs findings but cannot modify anything. Plan your workflow accordingly: Cursor reviews, you fix manually.

3. **Large-codebase `-p` prompts can timeout.** The 300s default timeout may expire before Cursor finishes reading 50+ files. For full-codebase reviews, use focused file lists or batch smaller scopes. `--mode ask` also has this constraint but copes better since it only reads, doesn't edit.

4. **`--mode plan` also prevents edits** but is more limited — it only outputs a plan summary. Use `--mode ask` for detailed findings with line numbers and severity classifications.

5. **Cursor `-p` mode runs without context of prior conversation.** Each `-p` invocation starts fresh. If you need to refine, either chain multiple invocations or use `--resume` to continue a session.

6. **Always use `--trust` in headless/CI mode.** Without it, Cursor may prompt for workspace trust and hang.

7. **Include FULL context in `-p` prompts.** Since each invocation starts cold, include: exact file paths, full import statements, component prop types, API endpoint shapes, and styling requirements. Fragment prompts ("create a player component") will produce stubs.

8. **Generous timeouts for complex tasks.** File creation (400+ lines) takes 60-120 seconds. Set terminal timeouts accordingly. Background mode with `notify_on_complete` is preferred for multi-minute tasks.

9. **Verify output after each invocation.** Exit code 0 doesn't guarantee the file was written or is correct. Check with `wc -l file.tsx` and `head -5 file.tsx`. If Cursor seems stuck with no output for 30+ seconds, it may be silently reading files — wait longer or kill and retry with a more focused prompt.

10. **Prefer `--model` over auto.** Explicit model selection avoids surprises. See model selection table in usage section above.

10. **For multi-file builds, use focused one-file-per-invocation prompts.** A single prompt asking for 5 files will produce one large response that Cursor may fail to split into files. Instead, call `agent -p` 5 times, each targeting a single file path with that file's specific requirements. This is more reliable and makes it easier to retry individual files.

11. **Cursor Pro monthly spend limit.** The Cursor Pro subscription has a shared spend cap across ALL models (Opus, GPT-5.5, Sonnet, Kimi, Gemini, Grok). When you hit the limit, every model returns the same "usage limit" error — the cap resets at the end of the monthly billing cycle. Do exactly one cheap probe with a fallback model if needed (e.g. `agent -p "Reply ONLY with CURSOR_OK" --model kimi-k2.5 ...`). If that also returns the same cap message, stop trying model variants; report the cap and either do the work directly or use the user's approved fallback agent. Do not burn time launching the full task repeatedly. If Cursor is capped and the user wants another agent, fall back to **OpenCode Go** (`opencode run -m opencode/big-pickle`) which has no per-model spend limit under the $10/mo Go subscription. See the `opencode` skill for usage.

11a. **Research-before-Cursor for high-stakes app work.** When the user asks to pass remaining Android/app work to Cursor and explicitly asks for best approach, first write a compact research note from official docs + GitHub/forums into the repo, then give Cursor a narrow chunk prompt that references that note. Include a hard rule that Cursor runs the project's verification commands after each implementation batch and stops on the first failure with a report file.

12. **Large audit output gets truncated in background process logs.** For audit-sized responses, include instructions to write findings to a file (e.g., `/tmp/audit.md`) so you can read it back with `read_file` rather than relying on the truncated process log.

## References

- `references/models.md` — Full model reference (tested, with speed tiers and recommendations)
- `references/code-review-pipeline.md` — Complete workflow: Cursor final-review → manual fix → commit