Cursor Agent SDK

Overview

Cursor Agent SDK (cursor/plugins) is an open-source TypeScript SDK that enables developers to build AI agent plugins for the Cursor code hosting platform. Released in August 2026, the SDK reached 5,074 GitHub stars with a weekly gain of 1,832 stars as Cursor's code hosting platform rapidly scaled past 1 million repositories.

The SDK defines a plugin specification for Cursor's expanding platform, allowing third-party developers to create AI-powered workflows that run on every pull request. This positions Cursor not just as an AI coding assistant, but as a full agent execution platform where plugins handle code review, automated testing, documentation generation, and deployment orchestration.

Written in TypeScript, the Cursor Agent SDK is designed to integrate seamlessly with Cursor's existing AI capabilities while providing an open extension point for the broader developer community. The SDK emerged as a direct response to developer frustration with Microsoft's Copilot pricing changes, offering an AI-native alternative to traditional CI/CD agent tooling.

Features

• Plugin specification: Standardized interface for building Cursor-compatible agent plugins
• PR-triggered agents: Automatic agent execution on every pull request
• TypeScript-native: Built for the TypeScript ecosystem with full type safety
• Built-in AI integration: Native access to Cursor's AI capabilities within plugins
• Code hosting platform integration: Deep integration with Cursor's code hosting infrastructure
• Open-source: Apache 2.0 licensed for unrestricted use and modification
• Rapid deployment: Plugins deploy directly within the Cursor platform ecosystem

Installation

# Install the SDK via npm
npm install @cursor/plugin-sdk

# Or clone from GitHub
git clone https://github.com/cursor/plugins.git
cd plugins
npm install

Quick Start

import { definePlugin, AgentPlugin } from "@cursor/plugin-sdk";

const codeReviewAgent: AgentPlugin = definePlugin({
  name: "code-review-agent",
  version: "1.0.0",
  description: "AI-powered code review agent",

  onPullRequest: async (context) => {
    const analysis = await context.ai.analyze(context.diff);
    return analysis.comments.map(comment => ({
      path: comment.file,
      line: comment.line,
      body: comment.suggestion,
      severity: comment.severity
    }));
  }
});

export default codeReviewAgent;

Core Concepts

Plugin as Agent

Each Cursor plugin is an autonomous agent that responds to platform events. The SDK provides a declarative interface where developers define what events trigger their agent and how the agent should respond. This event-driven model simplifies agent development by abstracting away infrastructure concerns.

PR-Centric Execution

The primary execution trigger is the pull request event. When a PR is opened, updated, or merged, all registered plugins are invoked in sequence. This creates a composable agent pipeline where each plugin contributes a specialized analysis or action.

Platform-Native AI Access

Plugins have direct access to Cursor's AI capabilities through the context.ai interface, eliminating the need for separate API key management or model routing. The platform handles model selection, rate limiting, and cost attribution automatically.

Advanced Features

Custom Agent Workflows

import { workflow, step } from "@cursor/plugin-sdk";

const deployWorkflow = workflow({
  name: "auto-deploy",
  steps: [
    step("test", { agent: "test-runner", parallel: true }),
    step("build", { agent: "build-optimizer", dependsOn: ["test"] }),
    step("review", { agent: "security-scan", dependsOn: ["test"] }),
    step("deploy", { agent: "deployment-agent", dependsOn: ["build", "review"] })
  ]
});

Event Subscription

import { on } from "@cursor/plugin-sdk";

on("push", async (ctx) => {
  // Run on every push to protected branches
  await ctx.ai.summarize(ctx.commitMessages);
});

on("issue.opened", async (ctx) => {
  // Auto-triage incoming issues
  const label = await ctx.ai.classify(ctx.issue);
  await ctx.issue.addLabel(label);
});

Cross-Repository Agents

Plugins can operate across multiple repositories, enabling organization-wide agent workflows:

import { orgScope } from "@cursor/plugin-sdk";

const orgCompliance = orgScope({
  check: "dependency-audit",
  schedule: "daily",
  reporter: "compliance-reporter"
});

Examples

Automated Test Generation

import { definePlugin } from "@cursor/plugin-sdk";

export default definePlugin({
  name: "test-generator",
  onPullRequest: async (ctx) => {
    const changedFiles = ctx.diff.getChangedFiles();
    const tests = await ctx.ai.generateTests({
      files: changedFiles,
      framework: "jest",
      coverageTarget: 80
    });
    await ctx.pr.addFiles(tests);
  }
});

Security Scanning Agent

import { definePlugin } from "@cursor/plugin-sdk";

export default definePlugin({
  name: "security-scan",
  onPullRequest: async (ctx) => {
    const vulnerabilities = await ctx.ai.scan({
      type: "sast",
      scan: ctx.diff,
      severity: "high"
    });
    if (vulnerabilities.length > 0) {
      await ctx.pr.comment({
        body: vulnerabilities.map(v =>
          `- **${v.severity}**: ${v.description} at ${v.file}:${v.line}`
        ).join("\n"),
        blocking: true
      });
    }
  }
});

Pros

• ✅ AI-native from day one: Designed for AI agent workflows, not bolted on
• ✅ TypeScript-native: Full type safety and IDE support
• ✅ Low barrier to entry: Simple plugin interface abstracts infrastructure
• ✅ Platform integration: Native access to Cursor's hosting and AI capabilities
• ✅ Event-driven: Natural fit for CI/CD and PR workflows
• ✅ Open specification: Extensible by the community

Cons

• ✅ Vendor-specific: Plugins only run on the Cursor platform
• ✅ Very early-stage: Only ~5K stars with limited production track record
• ✅ Platform lock-in: Deep integration creates migration friction
• ✅ Limited documentation: Rapid growth outpacing documentation coverage
• ✅ Single-language SDK: TypeScript-only, no Python SDK yet

When to Use

• Building AI agent plugins for Cursor's code hosting platform
• Teams migrating from GitHub to Cursor seeking CI/CD agent capabilities
• Developers wanting PR-triggered AI workflows without managing infrastructure
• Organizations building org-wide compliance and security agents

Resources

• GitHub Repository
• Cursor Documentation
• Plugin SDK API Reference