Cursor SDK

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:

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:

The smallest meaningful script (TypeScript):

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.

• Local and cloud runtimes

  The same SDK either runs the agent inline in your Node or Python process against files on disk, or in an isolated Cursor-hosted VM with the repo cloned.

• Plan and agent modes

  Choose plan mode to scope work first, or agent mode to implement directly, with per-run model overrides such as reasoning effort and max mode.

• MCP, hooks, and subagents

  Connect MCP servers over HTTP, SSE, or stdio, gate tool calls with file-based hooks at .cursor/hooks.json, and spawn named subagents from a parent run.