cursor-cli

name	cursor-cli
description	Authoritative reference for working on MultiTable's Cursor provider, driven by the Cursor CLI (`cursor-agent`) in headless `--print --output-format stream-json` mode. Trigger when the user mentions Cursor, cursor-agent, the Cursor adapter, CursorAdapter, stream-json / NDJSON events, `--resume` / `--continue`, `--mode plan|ask`, `--force` / `--yolo`, `--sandbox`, composer-2.5, `cursor-agent models`, `~/.cursor`, agent-transcripts, usage limits / rate limits (why they're off for Cursor; the cursor.com billing out-of-band path), or modifying anything under `packages/daemon/src/agent/providers/cursor.ts`, `packages/daemon/src/agent/providers/cursor-cli/`, or `packages/daemon/src/transcripts/cursorParser.ts`.
allowed-tools	Read, Grep, Glob, Edit, Write, Bash

Cursor CLI provider (cursor-agent)

This skill is strictly Cursor-only. Do not import other providers' SDK or protocol concepts (ACP session/prompt, Codex app-server JSON-RPC, the Claude Agent SDK query() loop) into Cursor code or docs — Cursor speaks its own headless NDJSON contract. See [[feedback_separate_sdks]].

The one fact that shapes everything

MultiTable drives Cursor as a one-shot child process per turn. Each turn spawns cursor-agent --print --output-format stream-json --stream-partial-output … "<prompt>", reads newline-delimited JSON (NDJSON) events from stdout until the terminal {"type":"result"} line, then the child exits. There is no long-lived child, no JSON-RPC, no persistent stdio session (unlike Hermes/Grok ACP or the Codex app-server).

Continuity across turns is by session id: the first turn's {"type":"system","subtype":"init", session_id} line gives the id; every subsequent turn re-spawns with --resume <session_id>, which replays full context. Abort = kill the child.

Auth, in one line

cursor-agent reads its own login state from ~/.cursor (written by cursor-agent login) or CURSOR_API_KEY. The adapter inherits process.env; missing creds fail the first turn. cursor-agent status prints the logged-in account.

Task → file map

Task	File
Adapter (turn loop, capabilities, modes)	packages/daemon/src/agent/providers/cursor.ts
Spawn + NDJSON line reader, executable resolver	packages/daemon/src/agent/providers/cursor-cli/runner.ts
Stream-json event TS types	packages/daemon/src/agent/providers/cursor-cli/events.ts
Mode/model/resume → CLI flags	packages/daemon/src/agent/providers/cursor-cli/args.ts
Transcript hydration (restart / past-agents)	packages/daemon/src/transcripts/cursorParser.ts
Model discovery (cursor-agent models)	packages/daemon/src/providers/discovery.ts → discoverCursor
Seed catalog	packages/daemon/src/providers/baselines.ts → CURSOR_BASELINE
Adapter registration + hydration branch	packages/daemon/src/agent/manager.ts

Deep dives

• reference/protocol.md — the full stream-json event union + tool_call shape.
• reference/modes.md — plan / ask / default / force, sandbox, allowlist.
• reference/models.md — cursor-agent models parsing; effort-in-model-id.
• reference/auth.md — login / CURSOR_API_KEY / ~/.cursor.
• reference/usage-limits.md — why usage limits are off and the out-of-band path.
• multitable/adapter.md — adapter architecture + capabilities rationale.
• multitable/persistence.md — on-disk transcript layout + cursorParser.
• pitfalls.md — the traps (Windows .cmd, double-counted deltas, …).