@buildify/cursor-agent

Node.js client runner for the Buildify Cursor Broker bundle. It connects to CursorBrokerTriggerNode, receives submitted tasks over SSE/HTTP, and executes them locally with @cursor/sdk.

Architecture

Buildify Workflow
  └── CursorBrokerTriggerNode (Java Netty HTTP server)
        └── CursorSubmitTaskNode (submit task)
        └── CursorCancelTaskNode (cancel task)
              ↕ HTTP + SSE
        @buildify/cursor-agent (this package)
              └── @cursor/sdk Agent.create() + agent.send()

Requirements

• Node.js 18+
• macOS (for install-service; foreground/daemon mode works on any OS)
• Buildify workflow with CursorBrokerTriggerNode running and reachable

Install

From this repository:

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

Or after publishing:

npm install -g @buildify/cursor-agent

Configuration

Initialize defaults:

buildify-cursor-agent config init

Edit ~/.buildify/cursor-agent.json:

{
  "server": "http://localhost:8080",
  "clientId": "my-macbook",
  "defaultCwd": "/Users/you/projects",
  "maxConcurrent": 2,
  "token": "",
  "logLevel": "info",
  "streamLogs": false,
  "requestTimeoutMs": 30000,
  "reconnectMinDelayMs": 1000,
  "reconnectMaxDelayMs": 30000
}

Or set values via CLI:

buildify-cursor-agent config set \
  server=http://192.168.1.10:9001 \
  clientId=my-macbook \
  defaultCwd=/Users/you/projects \
  token=broker_server_key

| Key | Description | |-----|-------------| | server | Base URL of the Java Cursor Broker (from CursorBrokerTriggerNode status) | | clientId | Unique agent identifier; must match CursorSubmitTaskNode.clientId | | defaultCwd | Default working directory when a task has no cwd | | maxConcurrent | Max parallel Cursor SDK runs (reported at connect) | | token | Bearer token when Buildify auth is enabled (Authorization: Bearer <serverKey>) | | logLevel | error, warn, info, or debug | | streamLogs | Print Cursor SDK stream messages to stdout for debugging | | requestTimeoutMs | HTTP timeout for broker calls | | reconnectMinDelayMs | Minimum reconnect backoff | | reconnectMaxDelayMs | Maximum reconnect backoff |

Show current config (secrets masked):

buildify-cursor-agent config show

Usage

Foreground

buildify-cursor-agent start

Press Ctrl+C to disconnect cleanly (DELETE /disconnect).

Debug logs

buildify-cursor-agent start --log-level debug --stream-logs

--stream-logs prints Cursor SDK stream events such as status, assistant text, thinking, and tool calls. The runner also reports task progress events back to CursorBrokerTriggerNode.

When a task provides cwd, the runner resolves it on the agent machine and creates the directory recursively if it does not already exist. If the path exists but is not a directory, the task fails.

Background daemon

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

PID file: ~/.buildify/cursor-agent.pid

macOS launchd service (like Docker Desktop auto-start)

Install a user LaunchAgent that starts on login and restarts on failure:

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

Logs:

• ~/.buildify/cursor-agent.log
• ~/.buildify/cursor-agent.log.err

Uninstall:

buildify-cursor-agent uninstall-service

Protocol

Implements the client side of the Cursor Broker HTTP API:

| Method | Path | Purpose | |--------|------|---------| | POST | /connect | Register client, get sessionId | | GET | /events | SSE stream (newTask and cancelled events) | | GET | /tasks/next | Pull next queued task | | POST | /tasks/{taskId}/events | Report received / progress / completed / failed / cancelled | | POST | /heartbeat | Keep-alive with runningCount | | DELETE | /disconnect | Clean shutdown |

Headers:

• Agent-Client-Id — agent identifier
• Agent-Session-Id — session from /connect

Model discovery:

• The runner sends its cached model list in /connect and /heartbeat.
• The model cache is refreshed from Cursor with the task-scoped cursorApiKey when a task starts.
• CursorSubmitTaskNode.model loads options from the selected clientId; if the agent has not reported models yet, it falls back to composer-2.5.

Buildify workflow setup

1. Add Cursor Broker Trigger node; note the listening port in node status.
2. Enable auth if needed and configure Cursor Broker Credential (serverKey).
3. Set token in client config to the same serverKey.
4. Add Submit Cursor Task node with matching clientId and task-scoped cursorApiKey.
5. Optionally add Cancel Cursor Task node and pass taskId to cancel queued or running tasks.
6. Start this runner on the target machine.

Development

npm install
npm run dev -- config show
npm run dev -- start
npm run build

License

MIT