Cursor Agent

The cursor agent wraps the Cursor IDE CLI (agent binary) to execute coding tasks within your workflow. It receives a prompt assembled from the phase role and upstream context, runs Cursor’s AI coding engine against your workspace, and captures the response.

This is the default agent in cliq. If a phase doesn’t specify an agent: field and no default_agent is configured in settings, the phase runs with cursor. It supports both standard phases (implementation, refactoring, code generation) and gate phases (code review, architectural verdicts).

Sample Phase

- name: implement
  agent: cursor
  role: developer
  depends_on: [architect]

Phase Configuration

The cursor agent supports two phase types:

Phase Type	Description
`standard`	Code generation, implementation, refactoring, documentation
`gate`	Code review, architectural review, quality verdicts

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	`"standard"` (default) or `"gate"`
`agent`	`string`	No	Agent name. Defaults to `cursor` when omitted
`role`	`string`	Yes	Role file name (without `.md`) from `.cliq/roles/`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`model`	`string`	No	Model override (e.g., `"claude-sonnet-4-20250514"`)

The role field is required — it tells the agent what persona to adopt and what kind of work to perform. Without a role, the agent has no instructions.

The model field is specified directly on the phase YAML, not in settings. This lets you use different models for different phases in the same pipeline.

Gate Behavior

When used as a gate agent, cursor reviews the upstream work and produces a verdict parsed from its output:

Verdict	Meaning
`PASS`	Work meets quality bar — pipeline continues
`ROUTE`	Work needs changes — routes back to a prior phase with feedback
`ESCALATE`	Work requires human intervention — pipeline halts

Settings

Key	Required	Default	Description
`agents.cursor.api_key`	Yes	—	API key for the Cursor CLI

Configure via:

echo $CURSOR_API_KEY | cliq settings agents.cursor.api_key --stdin --global

Output

The cursor agent writes code directly to the workspace and produces a natural language summary of the work performed. It does not produce structured data — its value is in the files it modifies and the explanation it provides.

Handoff Structure

{
    "data": null,
    "text": "The agent's natural language response and summary of work performed."
}

The text field is automatically injected into downstream phases’ prompts, giving subsequent agents full context of what was implemented.

Gate Output

When running as a gate phase, the handoff includes the verdict:

{
    "data": null,
    "text": "Code review complete. All error handling paths are covered and the caching strategy is sound. PASS"
}

The orchestrator parses the verdict keyword from the response and routes the pipeline accordingly.

Examples

Example: Implementation with review gate

A standard two-phase pipeline where cursor implements a feature and then reviews its own work (or another agent reviews it).

phases:
    - name: implement
      role: developer
      depends_on: [fetch-ticket]

    - name: review
      type: gate
      agent: cursor
      role: reviewer
      model: claude-sonnet-4-20250514
      depends_on: [implement]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Multi-agent pipeline with model override

Use different models for different concerns — a fast model for implementation, a reasoning model for review.

phases:
    - name: implement
      role: developer
      model: claude-sonnet-4-20250514

    - name: test
      role: test-writer
      model: claude-sonnet-4-20250514
      depends_on: [implement]

    - name: review
      type: gate
      role: senior-reviewer
      model: claude-sonnet-4-20250514
      depends_on: [implement, test]

Example: Cursor as the implicit default

Since cursor is the default agent, you can omit the agent: field entirely:

phases:
    - name: implement
      role: developer

    - name: review
      type: gate
      role: reviewer
      depends_on: [implement]

Both phases use the cursor agent because no agent: field is specified and no default_agent override exists in settings.

Setup

1. Install the Cursor CLI

The agent binary ships with Cursor IDE. Verify it’s on your PATH:

which agent

If not found, ensure the Cursor IDE is installed and its CLI tools are available in your shell.

2. Configure the API key

echo $CURSOR_API_KEY | cliq settings agents.cursor.api_key --stdin --global

3. Validate

cliq doctor agent cursor

This checks that the agent binary is on PATH and the API key is configured.