Cursor

Cursor is an optional provider. It stays off until you enable it on the machine. A Cursor step sends the code it reads to Cursor's service, so enable it only where that is allowed.

InstallCopy Anchor Link

Install Cursor's CLI from Cursor's own instructions. This page does not copy those steps.

CommandCopy Anchor Link

The runner looks up agent, then cursor-agent, unless cursor.command is set. It checks identity with --version and --help (the help text must mention Cursor, --output-format, and --workspace). There is no model call and no network. A binary that fails that check is refused.

Sign-inCopy Anchor Link

Sign in with agent login, or set CURSOR_API_KEY in the environment kusaw serve starts from.

--api-key is refused: it would be visible in the process list. Pass credentials through the environment, never as an argument.

kusaw validate reports signed in as yes or no. It does not print a key or an account.

The factory never stores credentials.

Switching one stepCopy Anchor Link

A new user can switch one step to Cursor as follows. The example uses factory demo and a step named review.

1. Enable Cursor on the machine. See Enabling Cursor.
2. kusaw config set --factory demo steps.review.provider cursor
3. kusaw validate --factory demo
4. Run a task (kusaw add while kusaw serve --factory demo is running).
5. Find cursor · configured-default in kusaw status for that run.

steps:
  review:
    provider: cursor

Without step 1, step 3 reports provider.not_enabled and exits 2. A kusaw.yaml cannot enable Cursor.

ModelsCopy Anchor Link

Model strings are whatever your Cursor CLI accepts. List them with agent models. Put a setting in steps.<id>.config.model. The placeholder in these docs is configured-default.

steps:
  review:
    config:
      model: configured-default

kusaw validate warns if that string is missing from agent models. The check is a warning so the factory still works offline. Cursor may refuse an unknown name when the step runs.

Read-only stepsCopy Anchor Link

Read-only steps (review, write-spec, retro, classify, score, and deliver summary text) pass --mode ask and then the git-tree guard. The guard compares the worktree after the step to a snapshot taken before it.

The guard covers tracked and untracked files inside the worktree. It does not cover ignored files, or files outside the worktree. A failure looks like: Step "review" must not change files, but Cursor changed: A path.txt. The worktree was left as is.

Build stepsCopy Anchor Link

Build steps pass --force. After the step, the ref guard fails a commit, reset, or checkout, and the push guard fails a push (GIT_CONFIG_* pushInsteadOf plus a refs/remotes check).

MCP servers and skillsCopy Anchor Link

For each Cursor step the runner writes a per-run .cursor/mcp.json in the worktree, listing only the servers that step declared. It restores or deletes that file when the step ends. ~/.cursor is never touched.

If Cursor would also load undeclared servers, the step is not started: The installed Cursor CLI would also load MCP servers <names> that step "<id>" did not declare. This step was not started. Disable those servers in Cursor, or use claude-code for this step.

Skills are inlined into the prompt. They are not loaded from a Cursor skills folder.

Cost and budgetsCopy Anchor Link

Tokens are reported. Cost isn't: the factory does not get a dollar figure from Cursor.

Optional prices go in cursor.pricing.<model>. The factory ships none.

cursor:
  pricing:
    configured-default:
      input_usd_per_token: 0.000001
      output_usd_per_token: 0.000005
      cached_usd_per_token: 0.0000001

limits.budget_tokens_per_run and limits.finally_budget_tokens count cached reads at a fraction: the cached-to-input price ratio from that model's price row, or 0.1 when there is no price.

limits:
  budget_tokens_per_run: 100000
  finally_budget_tokens: 20000

Cursor's usage arrives only at the end of a step, so a Cursor step can overshoot a token budget by up to one step. Time limits still apply during the step.

Known gaps versus Claude CodeCopy Anchor Link

Every capability-matrix row that is not enforced for Cursor:

• interactive — not supported. There is no interactive grill on Cursor; intake stays on Claude Code.
• read_only — guarded with --mode ask plus the git-tree guard. Ignored files and files outside the worktree are not covered.
• no_commit — guarded by the ref guard after the step.
• no_push — guarded by the push guard after the step.
• tool_allowlist — not supported and not emulated.
• system_prompt — partial: inlined into the prompt.
• skills — partial: inlined into the prompt.
• network — not supported (only inside Cursor's own sandbox, per its settings).
• reported_cost — not supported. Cost is computed from a price table, or unknown.
• token_usage — partial: unknown if Cursor does not report it.
• secret_store_denied — partial: per-attempt .cursor/cli.json. Read does not cover Grep/Glob.
• git_control_protected — guarded by the control-file guard after the step (the same as Claude Code).
• fork — not supported: the Cursor CLI has no fork flag.
• live_steering — not supported: stdin stays closed, so kusaw note reaches a Cursor step only when the next step starts.

The live table is generated in capabilities.

Tested versionCopy Anchor Link

The runner's flag names were checked against agent --help; no specific Cursor CLI version is pinned. Run agent --version and kusaw validate on the machine that runs the factory. kusaw validate refuses a binary whose help text does not match.