# @kentcdodds/cursor

## Intent

SDK for the [Cursor Cloud Agents API](https://cursor.com/docs/api). One compact
authenticated `request` helper against `https://api.cursor.com`, plus domain
helpers for agent lifecycle, runs, artifacts, workers, models, and repositories.
Plumbing is intentionally thin — there is no public Cursor OpenAPI scaffold.

## What it does

- Launch and manage Cursor Cloud Agents (create, list, follow-up runs, archive)
- Download agent artifacts and read run streams
- Inspect self-hosted pool workers and fleet utilization
- Discover models and GitHub repositories accessible through Cursor
- Read billed token cost for a Cloud Agent (`./agent-usage`) — dollars come
  from the API `cost` field, never from estimated token prices
- Call unwrapped Cursor API paths via `./request` (Enterprise Admin, Analytics,
  AI-Code-Tracking, Bugbot, etc.)

`createAgent` always enables ManagePullRequest so the cloud agent can push and open its own PR (do not open PRs via Kody as a substitute).

## Prerequisites / setup

1. Create an API key at [cursor.com/dashboard → API Keys](https://cursor.com/dashboard).
2. Save the **raw key** (not an Authorization header) in Kody as user secret
   **`cursorApiKey`**. This package sends it as Bearer; Cursor also accepts Basic.
3. Approve host `api.cursor.com` and package access to `cursorApiKey` if prompted.
4. Optional: user secret **`githubPersonalAccessToken`** — only needed for
   `agentsWithOpenGithubPrs`.
5. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths and smoke checks.

## Done when

- `cursorApiKey` is saved; host and package secret access are approved
- Read-only `apiKeyInfo` (`./me`) returns key metadata
- You can create an agent / run and list models when needed