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