cursor-sdk

What this skill does

# Cursor SDK

The Cursor TypeScript SDK (`@cursor/sdk`) runs Cursor agents programmatically. The same interfaces drives the local runtime (agent runs on your machine against your files) and the cloud runtime (agent runs on Cursor-hosted or self-hosted infrastructure against a cloned repo and opens PRs).

Use this skill to help someone **bootstrap a working integration quickly** and **avoid the handful of traps that bite new users**. Canonical docs live at [https://cursor.com/docs/api/sdk/typescript](https://cursor.com/docs/api/sdk/typescript); this skill only adds decision-making, failure-mode prevention, and ready-to-extend patterns.

## Voice and Posture

This skill helps the user **build** with the SDK. It is not the place to validate, congratulate, or sell the SDK as a choice. The user's intent is the input; your job is execution.

- **When the user names the SDK explicitly** (says "Cursor SDK", `@cursor/sdk`, `Agent.create`, `Agent.prompt`, etc.): assume they know what the SDK is and have decided to use it. Skip framing, skip pep talk, go straight to producing the integration. No "good news", no "the SDK is perfect for this", no "this is almost exactly the pattern X is designed for".
- **When the user describes a problem the SDK fits but doesn't name it** ("I want a bot that reviews my PRs", "I want a script that asks Cursor questions about my repo"): the SDK isn't yet a confirmed choice. Surface it as a question, briefly, then wait: *"The Cursor SDK is what I'd reach for here — want me to design it that way, or do you have a different runtime in mind?"* If they confirm, proceed. If they push back or want options, give options.
- **In either case, don't restate the user's intent back to them.** They know what they want. Get to the design.

Avoid these specific openers (and their close cousins):

- "Good news: this is exactly the pattern…"
- "The SDK is built for this shape."
- "Great, you've come to the right place."
- "This is almost exactly the X the SDK is designed for."
- Any lede that compliments the user's choice or restates their goal in flattering terms.

Prefer:

- Open with the design decision or the first thing they need to know.
- If you genuinely have a design choice to flag (local vs cloud, prompt vs send, sync vs stream), name it in one sentence and explain why; don't preface it with validation.

## When to open a reference file

Keep this page short. Read a reference file only when the user's task clearly falls inside it:


| If the user is...                                                                    | Read                                                           |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Picking between local and cloud runtime, or not sure which they should use           | [`references/runtime-choice.md`](references/runtime-choice.md) |
| Debugging auth (401s, "Missing CURSOR_API_KEY", team-vs-user keys, local vs prod)    | [`references/auth.md`](references/auth.md)                     |
| Handling errors, retries, rate limits, `CursorAgentError`, `result.status === error` | [`references/error-handling.md`](references/error-handling.md) |
| Consuming streams, picking event types, cancelling, or deciding stream vs wait       | [`references/streaming.md`](references/streaming.md)           |
| Configuring MCP servers (HTTP, stdio, cloud vs local transport, auth injection)      | [`references/mcp.md`](references/mcp.md)                       |
| Using sub-agents, resume, artifacts, listing/inspecting agents, `Agent.messages`     | [`references/advanced.md`](references/advanced.md)             |
| Building a specific integration (CI review bot, scheduled triage, chat, webhook)     | [`references/patterns.md`](references/patterns.md)             |


Everything below is the minimum needed for 80% of tasks.

## The Three Invocation Patterns

Almost every SDK integration collapses to one of three shapes. Pick the one that fits the job, don't mix them.

### 1. `Agent.prompt(...)` — one-shot

```typescript
import { Agent } from "@cursor/sdk";

const result = await Agent.prompt("Refactor src/utils.ts for readability", {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});
console.log(result.status, result.result);
```

Use for fire-and-forget scripts, GitHub Actions steps, or any "send this prompt, get a result, exit" flow. No streaming, no follow-ups, no cleanup to remember. If you're reaching for this and then immediately resuming, you wanted pattern 2 instead.

### 2. `Agent.create(...)` + `agent.send(...)` — durable with follow-ups

```typescript
import { Agent } from "@cursor/sdk";

const agent = Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

try {
  const run = await agent.send("Find the bug in src/auth.ts");
  for await (const event of run.stream()) {
    if (event.type === "assistant") {
      for (const block of event.message.content) {
        if (block.type === "text") process.stdout.write(block.text);
      }
    }
  }
  const result = await run.wait();

  // Follow-up keeps full conversation context.
  const run2 = await agent.send("Now write a regression test for it");
  await run2.wait();
} finally {
  await agent[Symbol.asyncDispose]();
}
```

Use when you need streaming, multi-turn conversation, or lifecycle operations (cancel, status listener). This is the shape of most non-trivial integrations.

### 3. `Agent.resume(...)` — pick up an existing agent later

```typescript
const agent = Agent.resume(previousAgentId, {
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});
const run = await agent.send("Also update the changelog");
await run.wait();
```

Use across process boundaries: a cron that continues last night's cleanup, a webhook that extends a user's agent, an interactive CLI that reloads conversation state. **Inline `mcpServers` are not persisted across resume** — pass them again on the resume call.

## Top Five Traps (read these before writing code)

These trip up almost every new integration. They're all easy to prevent once you know about them.

### 1. Missing `cloud: { repos }` silently defaults to local

`AgentOptions` doesn't require `local` or `cloud`; if you omit both, the SDK selects the local runtime. The trap: if you intended a cloud agent and forgot the `cloud:` field, you get a local agent silently — no error, just a local agent ID and a local executor. Always pass `cloud: { repos }` explicitly when you want cloud, and pass `local: { cwd }` explicitly for local even though it's the default. Picking the right runtime: see [`references/runtime-choice.md`](references/runtime-choice.md).

### 2. Two different kinds of failure, one instinct to conflate them

```typescript
try {
  const run = await agent.send(prompt);
  const result = await run.wait();
  if (result.status === "error") {
    // Agent started but failed mid-run. Inspect transcript, git state, tool outputs.
    console.error(`run failed: ${result.id}`);
    process.exit(2);
  }
} catch (err) {
  if (err instanceof CursorAgentError) {
    // Didn't start. Auth, config, network. Fix environment, retry.
    console.error(`startup failed: ${err.message}, retryable=${err.isRetryable}`);
    process.exit(1);
  }
  throw err;
}
```

`CursorAgentError` thrown → the run never executed (auth, config, network). `result.status === "error"` → the agent did work, and that work failed. Different fixes, different exit codes, different observability. Full taxonomy in [`references/error-handling.md`](references/error-handling.md).

### 3. Forgetting `await agent[Symbol.asyncDispose]()` leaks resources

The SDK holds handles to local executors, persisted run stores, and cloud API clients. Not disposing means leaked child processes, open databa