Cursor SDK
TypeScript SDK (
@cursor/sdk) to run Cursor agents outside the IDE — same harness/models as the editor, with local (your files) or cloud (cloned repo + PR) runtimes.
Announced Apr 2026: build agents on Cursor's runtime for CI/CD, embedded product features, and background automation. Open-sourced starter projects: coding-agent CLI, prototyping tool, agent kanban. Customers cited: Rippling, Notion, C3 AI, Faire. Source: X/@cursor_ai, 2026-04-29
Docs: cursor.com/docs/api/sdk/typescript. Executable patterns: Security and Review Skills skill + skills/personal/sdk/SKILL.md.
Version snapshot: @cursor/sdk latest is 1.0.22 as of 2026-06-25 on npm. The reviewed launch video thumbnail is an import { Agent } from "@cursor/sdk" code frame; the deeper source value is the self-thread's local/cloud runtime + starter-project claims, not the video itself. Source: npm registry, 2026-06-30; X/@cursor_ai visual artifact, 2026-04-29
Three invocation patterns
| Pattern | API | When |
|---|---|---|
| One-shot | Agent.prompt(...) |
Scripts, GH Actions — prompt → result → exit |
| Durable | Agent.create() + agent.send() + run.stream() |
Follow-ups, streaming, multi-turn |
| Resume | Agent.resume(...) |
Continue prior cloud/local run |
Requires CURSOR_API_KEY. Local runtime: { local: { cwd } }. Cloud: agent runs on Cursor infra against repo clone, can open PRs. Source: skills/personal/sdk/SKILL.md, 2026-06-13
import { Agent } from "@cursor/sdk";
const result = await Agent.prompt("Fix the auth bug in src/auth.ts", {
apiKey: process.env.CURSOR_API_KEY!,
model: { id: "composer-2" },
local: { cwd: process.cwd() },
});
Source: skills/personal/sdk/SKILL.md, 2026-06-13
vs other harness embeds
| Layer | Tool |
|---|---|
| Drive Cursor runtime from code | Cursor SDK (this page) |
| Drive Claude Code / Codex / Pi in app | AI SDK HarnessAgent (AI SDK 7) |
| Recursive fan-out in IDE | Cursor Orchestrate Skill (built on SDK) |
| Daily-driver interactive harness | Cursor Harness, Claude Code Harness |
Stack fit (Kevin)
- Background bugfix / briefing automations —
code-bugfix,project-briefingcloud runners; pair withautomations/*.cursor-automation.md. - Agent Machines — programmatic background workers on Cursor cloud runtime vs self-hosted Hermes Agent (Nous Research) on tailnet.
- Never default for Dedalus product — customer-facing agents should use AI SDK HarnessAgent or owned loop; SDK is for Kevin's dev infra.
- Configure MCP servers on SDK agents same as IDE when tools need Supabase/Linear/etc.
Timeline
- 2026-06-30 | Deep-reviewed the Cursor SDK bookmark row, repaired the local thumbnail artifact, and added the current npm snapshot (
@cursor/sdk@1.0.22, modified 2026-06-25). Decision: keep Cursor SDK as Kevin-infra automation/harness embedding, not as the default customer-facing product agent layer. Source: X/@cursor_ai, 2026-04-29; Source: npm @cursor/sdk, 2026-06-30 - 2026-04-29 | Cursor SDK announced; local + cloud runtime; starter repos; enterprise customers cited. 8,750 likes, 5,069 bookmarks. Source: X/@cursor_ai, 2026-04-29
- 2026-06-12 | Wiki page from bookmark absorption. Source: x-bookmark-absorb, 2026-06-12
- 2026-06-13 | Quality remediation: API patterns from SDK skill, tier promoted to 1, harness comparison table. Source: Agent, 2026-06-13