# Cursor Agent

> Use the Cursor CLI agent mode for IDE-integrated coding with project rules and repo-aware edits

- Skill: `markus-global/cursor-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add markus-global/cursor-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markus-global/cursor-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: markus-global (https://skillmd.com/u/markus-global)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/markus-global/cursor-agent

---


# Cursor Agent

Cursor Agent (`cursor` binary) runs the Cursor IDE's agent mode from the command line. Markus invokes it via `invoke_coding_tool({ tool: "cursor-agent", ... })`. Use it when the project has Cursor-specific configuration (`.cursor/rules`) or when IDE-integrated, project-aware editing is the best fit.

## Installation

Install Cursor from [https://cursor.sh](https://cursor.sh), then enable the shell command:

1. Open Cursor → Command Palette → "Install 'cursor' command in PATH"
2. Verify: `cursor --version`

Check availability with `markus doctor`. Requires authentication via `cursor agent login` (browser-based) or `CURSOR_API_KEY` env var.

## How Markus Invokes Cursor Agent

Markus runs Cursor in CLI agent mode:

```bash
cursor agent --print --output-format stream-json --workspace <workdir> --trust --force "<prompt>"
```

| Flag | Purpose |
|---|---|
| `--print` | Non-interactive mode |
| `--output-format stream-json` | Emits structured JSON events for progress parsing |
| `--workspace <workdir>` | Specifies the repo root for project context |
| `--trust --force` | Auto-trusts the workspace without interactive prompts |

Additional args can be configured via `CodingToolConfig.defaultArgs`.

## .cursor/rules Context Files

Cursor projects use **`.cursor/rules/`** for persistent agent instructions. Rule files (`.mdc` or `.md`) define:

- Coding standards and naming conventions
- Architecture decisions and patterns to follow
- Test requirements and deployment procedures
- Files or areas agents should not modify

Cursor Agent reads these rules automatically when operating in a project directory. Well-maintained rules significantly improve output quality.

### Markus Task Context Injection

When you pass `task_id` to `invoke_coding_tool`, Markus writes task-specific context to:

```
.cursor/rules/markus-task.mdc
```

This file contains the full Markus task context (title, description, subtasks, dependencies, progress-reporting CLI commands). It sits alongside your project's permanent rules and takes effect for the coding session.

**Important:**

- Markus creates the `.cursor/rules/` directory if it doesn't exist
- The `markus-task.mdc` file is regenerated each invocation — do not store permanent rules there
- Keep long-lived project rules in separate files (e.g., `coding-standards.mdc`, `architecture.mdc`)

### Example Project Rules Structure

```
.cursor/rules/
├── coding-standards.mdc    # permanent — naming, formatting, test requirements
├── architecture.mdc        # permanent — module boundaries, patterns
└── markus-task.mdc         # ephemeral — injected by Markus per task
```

## Working Directory Considerations

The `workdir` parameter is critical for Cursor Agent:

### Use the Repository Root

Always pass the **absolute path to the git repository root** as `workdir`:

```
workdir: "/Users/agent/projects/my-app"
```

Cursor Agent resolves `.cursor/rules/` relative to this directory. Pointing at a subdirectory may cause rules to be missed.

### Multi-Repo Projects

If the task spans multiple repositories, invoke Cursor Agent **once per repository** with repo-specific prompts:

```
invoke_coding_tool({
  tool: "cursor-agent",
  prompt: "Implement the API client changes described in the task context.",
  workdir: "/path/to/backend-repo",
  task_id: "task-789"
})
```

### Git State

Ensure the working directory is a clean git checkout (or at least understand existing uncommitted changes). Cursor Agent edits files in-place. Review with `git status` and `git diff` before applying.

### Environment Variables

Markus injects these env vars during context injection:

| Variable | Purpose |
|---|---|
| `MARKUS_API_URL` | API server for task operations |
| `MARKUS_TASK_ID` | Current task ID |
| `MARKUS_CLI` | Path to the markus CLI binary |

Cursor Agent subprocesses can use these if the injected context references CLI commands for progress reporting.

## Usage Patterns

### Rule-Driven Feature Implementation

```
invoke_coding_tool({
  tool: "cursor-agent",
  prompt: "Implement the user settings page following the patterns in .cursor/rules/frontend.mdc. Use existing component library imports. Add unit tests.",
  workdir: "/path/to/frontend-repo",
  task_id: "task-789"
})
```

### Convention-Heavy Refactor

```
invoke_coding_tool({
  tool: "cursor-agent",
  prompt: "Migrate all API routes in src/routes/ to the new error-handling pattern defined in .cursor/rules/api-conventions.mdc. Update tests accordingly.",
  workdir: "/path/to/repo",
  task_id: "task-789"
})
```

### Monorepo Package Work

```
invoke_coding_tool({
  tool: "cursor-agent",
  prompt: "Add the coding-tools skill templates under templates/skills/. Follow the existing skill.json + SKILL.md pattern from templates/skills/Learning Habits/.",
  workdir: "/path/to/markus-monorepo",
  task_id: "task-789"
})
```

## Model and Mode Selection

Cursor Agent supports per-invocation model and mode overrides:

```
invoke_coding_tool({
  tool: "cursor-agent",
  prompt: "...",
  model: "auto",     // optional: CLI-specific model (auto, composer-2.5, etc.)
  mode: "plan",      // optional: plan | ask
})
```

### Important: CLI Model Limitations

The Cursor `agent` CLI only accepts a limited set of CLI-specific model identifiers: `auto`, `composer-2.5`, etc. **Cursor Cloud API models** (Claude, GPT families) **are not available via the CLI** — they only work via the REST API.

The Settings UI only shows CLI-compatible models to prevent selection errors.

### Critical cost fact: Auto Mode vs Max Mode

**Not specifying `--model` uses Auto mode** — this is unlimited on paid Cursor plans and very cheap (or free). The moment you specify a model name, Cursor enters **Max Mode**, which bills per-token from the monthly credit pool.

| Mode | Cost | When to use |
|---|---|---|
| Auto (no `--model`) | Free / unlimited on paid plans | Default for most tasks |
| Max Mode (explicit `--model`) | Per-token billing, varies by model | Only when task needs specific model capabilities |

**Warning:** Opus in Max Mode consumes credits approximately 20x faster than Auto mode. **Only specify `--model` when the task genuinely needs a specific model's capabilities.** For most tasks, Auto mode is the correct and cost-effective choice.

### Mode guidance

- `plan` — Analyze architecture first, don't make changes yet. Good as a first step for complex tasks.
- `ask` — Answer questions about the codebase without making changes.
- Default (no mode) — Full agent mode, makes edits. Use for implementation.

### Mode chaining pattern

For complex tasks:

1. `mode: "plan"` — "Analyze the codebase and propose an implementation plan for..."
2. Default agent mode — "Implement the plan: [paste plan from step 1]"
3. `mode: "ask"` — "Review the changes and identify any issues"

### Cost strategy

- **Default to no model override** (Auto mode) — it handles most tasks well and is free/cheap
- Only specify a model when Auto mode produces poor results or the task clearly needs specific capabilities
- **Voluntarily call `request_user_approval` before specifying expensive models** (Opus) since it enables Max Mode billing

## When to Choose Cursor Agent

| Choose Cursor Agent | Choose something else |
|---|---|
| Project has rich `.cursor/rules/` | No Cursor config, generic repo → `claude-code` |
| Team standardized on Cursor conventions | Need stream-json cost tracking → `claude-code` |
| IDE-style project-aware edits | Quick one-file fix → `codex` |
| Frontend/UI work with component rules | Deep backend exploration → `claude-code` |

## Error Handling

Cursor Agent may include some token data in result events. Evaluate results by:

1. `result.success` and `result.summary`
2. `result.modifiedFiles` — do they match expected scope?
3. `result.testResult` from quality verification
4. Manual `git diff` review in `workdir`

If Cursor Agent ignores project rules, verify:

- `workdir` points to the repo root (where `.cursor/rules/` lives)
- Rule files use correct `.mdc` format and are not empty
- The prompt explicitly references relevant rule files

If output quality is poor after 2 attempts, switch to `claude-code` with equivalent prompt and CLAUDE.md context.

## Best Practices

- Maintain `.cursor/rules/` with clear, actionable project conventions
- Always pass absolute repo root as `workdir`
- Pass `task_id` so `markus-task.mdc` carries task context
- Reference specific rule files in prompts when multiple rules exist
- Review diffs carefully — Cursor Agent may interpret rules differently than expected
- **Default to Auto mode (no model override) for cost-effectiveness**
- Only specify models when Auto mode is insufficient

## Mode Chaining for Quality

Use Cursor Agent modes strategically:
1. **Plan mode**: `invoke_coding_tool({ tool: "cursor-agent", mode: "plan", prompt: "..." })` — analyze before implementing
2. **Agent mode** (default): Full implementation
3. **Ask mode**: `invoke_coding_tool({ tool: "cursor-agent", mode: "ask", prompt: "..." })` — targeted questions about the codebase

For complex tasks, always plan first. Review the plan before proceeding to implementation.

## Project Rules Integration

Cursor Agent reads `.cursor/rules/` automatically. When `task_id` is provided, Markus injects task context into `.cursor/rules/markus-task.mdc`. This means Cursor Agent automatically understands:
- Task requirements and acceptance criteria
- Project conventions and constraints
- Upstream/downstream dependencies

## Rules

- **DO** use when the project has Cursor rules configured
- **DO** pass the repository root as `workdir`
- **DO** keep permanent rules separate from `markus-task.mdc`
- **DO** default to Auto mode (no `--model`) for cost savings
- **DO** request approval before using expensive models in Max Mode
- **DO NOT** store permanent instructions in `markus-task.mdc`
- **DO NOT** use for repos with no Cursor configuration unless other tools are unavailable
- **DO NOT** apply changes without reviewing diffs against project rules
- **DO NOT** specify `--model` by default — it triggers Max Mode billing