Buildify Cursor Agent

buildify-cursor-agent connects Buildify Agent Broker to the local Cursor CLI. It pulls cursor.task jobs from Broker, runs them through Cursor agent acp, then reports task results, token usage, and errors back to Broker.

Requirements

• Node.js 18 or newer
• Cursor CLI installed on the agent machine
• A Cursor API key for the task model
• Network access from the agent machine to Buildify Agent Broker

Check Cursor CLI:

agent --version
agent --help

If agent is not available, install the Cursor CLI:

buildify-cursor-agent install-cursor

Install

From npm:

npm install -g @buildify-cli/cursor-agent

From this repository:

cd buildify-cursor-agent
npm install
npm run build
npm link

Verify:

buildify-cursor-agent --version
buildify-cursor-agent --help

Quick Start

Create the default config file:

buildify-cursor-agent config init

Set Broker connection values:

buildify-cursor-agent config set \
  server=http://localhost:8080 \
  token=<broker-token> \
  clientId=<agent-client-id>

Optionally set a default Cursor API key for model discovery:

buildify-cursor-agent config set cursorApiKey=<cursor-api-key>

Start in the foreground:

buildify-cursor-agent start --logs

Start as a background daemon:

buildify-cursor-agent start --daemon
buildify-cursor-agent status
buildify-cursor-agent stop

Install as a macOS launchd service:

buildify-cursor-agent install-service
buildify-cursor-agent status
buildify-cursor-agent uninstall-service

Configuration

Config file:

~/.buildify/cursor-agent.json

Show current config:

buildify-cursor-agent config show

Set config values:

buildify-cursor-agent config set key=value [key=value ...]

Common keys:

| Key | Default | Description | | --- | --- | --- | | server | http://localhost:8080 | Buildify Agent Broker URL | | clientId | host name | Agent client ID registered with Broker | | token | empty | Broker auth token | | defaultCwd | ~/projects | Default working directory on the agent machine | | maxConcurrent | 2 | Max parallel Cursor tasks | | cursorApiKey | empty | Cursor API key used for model discovery | | cursorBin | agent | Cursor CLI executable path | | defaultModel | composer-2.5 | Fallback model when discovery fails | | usageProbe | true | Probe Cursor print mode for usage if ACP omits it | | logs | false | Print local agent logs |

Configuration priority:

1. CLI flags
2. Environment variables
3. ~/.buildify/cursor-agent.json
4. Built-in defaults

Environment Variables

| Variable | Description | | --- | --- | | BUILDIFY_SERVER | Broker server URL | | BUILDIFY_TOKEN | Broker auth token | | BUILDIFY_CLIENT_ID | Agent client ID | | BUILDIFY_LOGS | Enable local logs | | CURSOR_API_KEY | Cursor API key | | BUILDIFY_CURSOR_API_KEY | Cursor API key alias | | BUILDIFY_CURSOR_BIN | Cursor agent executable path | | BUILDIFY_CURSOR_USAGE_PROBE | Enable or disable usage probing |

Example:

BUILDIFY_SERVER=http://localhost:8080 \
BUILDIFY_TOKEN=<broker-token> \
BUILDIFY_CLIENT_ID=cursor-local \
CURSOR_API_KEY=<cursor-api-key> \
buildify-cursor-agent start --logs

CLI Commands

buildify-cursor-agent start [options]
buildify-cursor-agent stop
buildify-cursor-agent status
buildify-cursor-agent install-service
buildify-cursor-agent uninstall-service
buildify-cursor-agent install-cursor
buildify-cursor-agent config init
buildify-cursor-agent config show
buildify-cursor-agent config set key=value [key=value ...]

start options:

| Option | Description | | --- | --- | | --daemon | Run in background | | --foreground | Run in foreground | | --server <url> | Override Broker URL | | --token <token> | Override Broker token | | --client-id <id> | Override client ID | | --logs | Enable local logs | | --request-timeout-ms <ms> | HTTP request timeout |

Use In Buildify

Use AgentCursorSubmitTaskNode to submit Cursor tasks.

Required fields:

• Broker instance
• Client ID matching the running buildify-cursor-agent
• Cursor model
• Cursor API key
• Prompt
• Working directory (cwd)

Important: cwd is a path on the machine where this agent runs. It is not the Buildify server path. If the directory may not exist, enable “create working directory if missing”.

Cursor Task Fields

The runner supports these task values from Buildify:

• prompt: user instruction sent to Cursor
• cwd: local working directory on the agent machine
• model: Cursor model, for example composer-2.5
• cursorApiKey: Cursor API key used by the task
• conversationId: optional ACP session ID to resume
• mcpServers: optional MCP server definitions passed to Cursor ACP
• createCwdIfMissing: whether the agent may create cwd

Each task starts a fresh Cursor ACP subprocess:

agent --api-key <cursor-api-key> --model <model> acp

Usage Reporting

Cursor ACP may not always report token usage directly. When usageProbe=true, this agent performs a best-effort usage probe after the task finishes.

Reported usage can include:

• input tokens
• output tokens
• reasoning tokens
• cache read/write tokens
• source metadata such as acp, print-probe, or estimated

If usage cannot be read from Cursor, the runner falls back to an estimate so Broker still receives a useful usage payload.

Debugging

Enable normal logs:

buildify-cursor-agent start --logs

Check daemon/service status:

buildify-cursor-agent status

Install or verify the Cursor CLI:

buildify-cursor-agent install-cursor

For local ACP investigation, use the debug script:

node debug-acp.mjs \
  --model composer-2.5 \
  --api-key <cursor-api-key> \
  --prompt "say hello"

Common Errors

Task is missing cursorApiKey

The task did not include a Cursor API key. Set the key in Buildify ModelSelect or pass cursorApiKey in the task payload.

Cursor API key is invalid

Check whether the API key is valid and not redacted. The task must pass the real key value, not a masked placeholder.

Cursor usage limit reached

The selected Cursor account or model has reached its usage limit. Try another model or wait for quota reset.

Working directory does not exist

The cwd path does not exist on the agent machine and createCwdIfMissing is disabled. Use a local path on the agent machine or enable directory creation.

Cursor CLI not found

The agent binary is missing or not on PATH. Run:

buildify-cursor-agent install-cursor

Or configure:

buildify-cursor-agent config set cursorBin=/path/to/agent

Development

npm install
npm run typecheck
npm run build
npm run build:dev

Before publishing:

npm run typecheck
npm run build
npm pack --dry-run