Cursor SDK

The Cursor SDK is the official programmatic interface to the same agent runtime that powers the Cursor IDE, CLI, and web app. Maintained by Cursor (Anysphere), it ships as both a Python and TypeScript library under a proprietary license. First released in 2026, the SDK occupies a unique niche: it is both an agent runtime (you run the agent inside your own process or on Cursor-hosted cloud VMs) and an inference SDK (it wraps the composer-2.5 model family with planning, tool use, and memory).

The problem it solves is straightforward: teams that need a production-proven coding agent embedded into CI/CD, internal tools, or multi-repo workflows no longer have to build one from scratch. Instead, they get the same agent loop that already handles millions of editor actions daily. The SDK is optimized for scripting Cursor’s coding agent in automation contexts, not for general-purpose chat or non-code workflows. Its design philosophy is “take our agent harness and run it anywhere” — local filesystem, cloud VM, or self-hosted worker — without reinventing repository indexing, MCP integration, or subagent orchestration.

Within the agent framework landscape, Cursor SDK competes most directly with task-specific coding agents (Claude Code SDK, OpenAI Codex CLI) rather than general-purpose multi-agent orchestrators like LangChain or CrewAI. It is not a framework for building arbitrary agent architectures; it is a purpose-built runtime for one very capable agent that can be scripted, parallelized, and embedded.

The Cursor SDK is imperative and code-first. You write a Python or TypeScript script that imports the SDK, creates an agent instance, configures its runtime (local or cloud), and calls methods to execute tasks. There are no declarative YAML configs, no graph definitions, and no chain-of-thought templates. The core abstraction is the agent run: a single session that can work in either plan mode or agent mode. In plan mode, the agent analyzes the task, scopes the work, and produces a plan before taking action. In agent mode, it jumps directly to implementation, reading files, running commands, and editing code.

Control flow is synchronous or streaming. The agent emits a stream of events (tool calls, file edits, status updates) that your script can consume for logging, progress bars, or human-in-the-loop approvals. The SDK provides a Run object with methods like agent.run({ task }) that returns an AgentRunResult or an AsyncIterable of events.

A minimal agent in TypeScript looks like this:

1import { Agent } from '@cursor/sdk';
2
3const agent = new Agent({
4  runtime: 'local', // runs inline in your process
5  projectPath: '/path/to/repo',
6  model: 'composer-2.5',
7});
8
9const result = await agent.run({
10  task: 'Add error handling to all API routes in src/api',
11  mode: 'plan', // or 'agent'
12});

Key abstractions beyond the agent itself:

• MCP servers – Connect external tools via HTTP, SSE, or stdio. Each server provides tools that the agent can call.
• Hooks – File-based gatekeeping at .cursor/hooks.json. You can intercept tool calls (e.g., block rm -rf in CI) or require approval before file writes.
• Subagents – Spawn named subagents from a parent run. Each subagent gets its own task, model overrides, and event stream. Useful for parallel exploration or dividing a large refactor.
• Context – The SDK automatically indexes the repository (file structure, dependencies) and provides that context to the agent. No manual chunking or RAG setup required.

The runtime switch (local vs cloud) is a one-line configuration. Local execution runs the agent in your own Node or Python process, reading and writing files on the local filesystem. Cloud execution spins up an isolated Cursor-hosted VM, clones the repo, and runs the agent there. The SDK abstracts the exact same interface for both.

The Cursor SDK delivers a set of capabilities that are directly useful for production coding workflows:

• Multi-agent coordination – Not a generic swarm pattern, but purposeful: you can spawn subagents from a parent run to work on independent sub-tasks. The parent monitors results and can feed them back into its own loop. This is designed for dividing a large refactor or audit across multiple VMs.
• Streaming – Every agent run emits a stream of typed events: tool calls, file modifications, thought steps, errors. You can pipe these to a real-time dashboard, log them, or use them to gate further actions.
• Tool use – The agent can call any tool exposed via MCP (HTTP, SSE, stdio) or built-in file/command tools. Tool access is controlled by hooks.
• Human in the loop – Hooks can pause execution and wait for human approval before a tool call proceeds. This is critical for safe CI/CD automation.
• Memory – The agent maintains a working context window that includes the repository, previous steps, and any artifacts generated. No long-term persistent memory across runs (unless you implement it externally).
• Type-safe – Both TypeScript and Python SDKs provide full type definitions. API responses are strongly typed.
• Self-hostable – You can run the SDK locally on your own hardware. The cloud runtime is optional.
• Cloud-hosted – The Cursor-managed VM execution is available for teams that want isolation without managing infrastructure.

Specific maintainer-provided features worth calling out:

• Local and cloud runtimes – The same SDK call works on both. Cloud VMs come with the repo cloned and pre-indexed, which is a major time saver for CI pipelines.
• Plan and agent modes – Plan mode is especially valuable for PR workflows: have the agent scope the change first, then optionally implement. Per-run model overrides let you adjust reasoning effort per task.
• MCP, hooks, and subagents – MCP is the transport layer for external tools. Hooks are JSON files that act as a middleware to approve or deny tool calls based on the task context and file paths. Subagents are named and separately configurable, allowing you to run parallel audits or fix chunks independently.

Teams deploying the Cursor SDK tend to fall into three categories, each reflecting a known use case.

Coding agents in CI/CD – The most common pattern. A pipeline task uses the SDK to run agent mode against a local checkout, performs a set of edits (e.g., migrating a deprecated API, fixing lint errors, adding tests), and optionally creates a PR via the autoCreatePR flag. Idempotency keys ensure the agent only runs once per commit even if the pipeline restarts. This replaces fragile shell scripts and regex-based code mods with a model that understands the full codebase.

Parallel agent fleets – Teams with large monorepos fan out work across many cloud VMs. For example, upgrading a shared library that touches 50 packages: spawn one agent per package, each in its own VM, each with the same base repo but a different sub-task. The parent run waits, collects diffs, and merges them. This cuts a week-long manual effort to hours.

Multi-repo refactors and audits – The SDK supports a target list of up to 20 repositories. A single agent run clones each repo, executes the same task, and collects results. Useful for enforcing security policies (e.g., “remove all hardcoded secrets in every JavaScript repo”) or rolling out a change across microservices.

The SDK is a poor fit for workloads that are not code-based (e.g., customer support chatbots, document summarization) because its model and context are optimized for repository understanding. It is also not suited for long-running background agents that need persistent state across days. For those, you would pair the SDK with an external database and orchestration layer.

To start building with the Cursor SDK, install it from npm or PyPI:

1npm install @cursor/sdk
2# or
3pip install cursor-sdk

The smallest meaningful script (TypeScript):

1import { Agent } from '@cursor/sdk';
2
3const agent = new Agent({
4  runtime: 'local',
5  projectPath: process.cwd(),
6});
7
8const stream = agent.run({
9  task: 'List all files that contain the word "TODO"',
10  mode: 'agent',
11});
12
13for await (const event of stream) {
14  console.log(event.type, event.data);
15}

What you need around it:

• A Cursor team plan and API key (the SDK is proprietary and billed through your Cursor account).
• Node.js 18+ or Python 3.10+.
• For cloud execution, no additional infrastructure. For local execution, enough compute to run the agent model (composer-2.5 runs on Cursor’s servers, not locally; the “local” runtime means the agent process runs locally but still calls the Cursor API).

Documentation is available at [cursor.com/sdk](https://cursor.com/sdk). Community support is primarily through the Cursor forum and the @cursor/sdk GitHub repository. The SDK is in public beta, so expect API changes and limited documentation depth initially.

Cursor SDK vs. Claude Code SDK (Anthropic) – Both are purpose-built coding agents exposed as an SDK. Claude Code SDK runs locally via the claude CLI and is open-source; Cursor SDK is proprietary and offers cloud VMs. Cursor’s advantage is the first-class TypeScript and Python package, the hooks system for fine-grained access control, and multi-repo support. Claude Code SDK wins on transparency and the ability to swap models (you can use any Anthropic model). Choose Cursor if you want a managed cloud execution environment and tight MCP integration; choose Claude Code SDK if you need open-source code and model flexibility.

Cursor SDK vs. OpenAI Codex CLI – Codex CLI is a command-line tool, not a library you can embed. The Cursor SDK gives you programmatic control (streaming events, subagents, hooks) that Codex CLI does not. If you need to build a custom pipeline or product around a coding agent, Cursor SDK is the more extensible option. If you just want to run ad-hoc code generation from the terminal, Codex CLI is simpler.

Cursor SDK vs. LangChain / CrewAI – These are general-purpose agent frameworks. Cursor SDK is for a single, specific, highly optimized coding agent. You would not use LangChain to build a coding agent unless you wanted full control over every component (indexing, model selection, tool design). Cursor SDK is the “batteries included” choice for code tasks; LangChain/CrewAI are the “build your own” alternatives. The trade-off: Cursor SDK is faster to start but locked to Cursor’s models and pricing.

When to choose Cursor SDK: Your team needs a reliable, testable coding agent for CI, refactors, or audits. You already use Cursor IDE or are comfortable with a proprietary platform. You want cloud execution without managing VMs.

When to choose an alternative: You need to bring your own LLM provider, require open-source code for security audit, or need a general-purpose agent framework that can also handle non-code tasks.