cursor-agent

Install, configure, and operate the Cursor Agent CLI for parallel task fanout.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/diazMelgarejo/orama-system --skill cursor-agent-diazmelgarejo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cursor-agent
Source: https://github.com/diazMelgarejo/orama-system/tree/main/bin/orama-system/skills/cursor-agent
Command: npx skills add https://github.com/diazMelgarejo/orama-system --skill cursor-agent-diazmelgarejo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Running mechanical coding subtasks in the main orchestration session wastes context and serializes work that could run in parallel. This Skill provides the operational playbook for installing, authenticating, and dispatching Cursor's background agent CLI (cursor-agent) so light tasks fan out concurrently while the main session handles judgment work. ## Core Features & Use Cases - Cross-platform installation and authentication: Bash installer for macOS/Linux, PowerShell for Windows, plus OAuth login or CURSOR_API_KEY environment variable setup. - Model selection policy: Three-tier policy defaulting to composer-2.5 for light tasks, auto as fallback, and orchestrator-override models only when explicitly demanded. - Parallel fanout with safety discipline: Headless --print jobs with JSON output, file-disjoint clustering, verification of self-reported results against repository-relative paths, and concurrent-job race awareness. - Worktree isolation and MCP integration: Isolated git worktrees for write tasks and MCP server management including platform-specific CRG endpoints. - Use Case: During Stage 4 execution, dispatch a cursor-agent job to generate pytest stubs and another to scan for TODO comments while the main session performs architecture review, then collect and verify both results. ## Quick Start Ask the agent to install cursor-agent, log in, and fan out a light task such as adding type annotations to a script using the composer-2.5 model in headless print mode.

Frequently Asked Questions about cursor-agent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I install the cursor-agent CLI on macOS or Linux?

Run the official installer with curl https://cursor.com/install piped to bash, which places the binary at ~/.local/bin/cursor-agent and adds that directory to PATH. Verify with cursor-agent --version and cursor-agent models.

How do I run cursor-agent tasks in parallel?

Dispatch multiple headless jobs with cursor-agent --print --model composer-2.5 in the background, writing JSON output to a repo-relative artifact directory, then collect them with wait. Partition tasks so no two jobs write the same file.

Which model should I use for cursor-agent fanout tasks?

Use composer-2.5 as the default for all light parallel tasks, with auto as fallback when composer-2.5 is unavailable. Reserve claude-4.6-sonnet-medium only for explicit orchestrator overrides, never as a general default.

Is cursor-agent the same as the agent command?

No. cursor-agent at ~/.local/bin/cursor-agent is Cursor's background agent CLI, while agent at ~/.grok/bin/agent is the Grok Build TUI, a separate product. Always invoke Cursor agents as cursor-agent, never as bare agent.

Does cursor-agent work on Windows?

Yes. Install via PowerShell with iwr -UseBasicParsing https://cursor.com/install.ps1 | iex, which places shims under %LOCALAPPDATA%\cursor-agent. It can be invoked from PowerShell or Git Bash, including from Hermes-scripted workflows.

Why should I not trust a cursor-agent job's completion report?

A job's JSON summary is a claim, not a result. After wait, verify the actual artifact using repository-relative paths, canonicalize with realpath to confirm it stays under the repo root, and re-check with git ls-files or by re-running tests.