Bot Development Kit (BDK)
The Bot Development Kit (BDK) lets you define, test, and deploy agents as code. It uses the Cursor SDK harness that powers Bugbot, Security Review, Approval Bot, and Rollouts.
A BDK project is a folder of Markdown and TypeScript. Combine deterministic code with model judgment, then make the bot or agent available in source control, Slack, issue trackers, and Cursor.
Why use it
-
Bots and agents live in your repo. Instructions, tools, and evals are files you review, version, and ship like the rest of your code.
-
Cursor runs the loop. You write the instructions and tools. Your agent gets Cursor's models, tool calling, skills, MCP, and subagents. Each turn runs on your host.
-
Use it where you work. Trigger a project from source-control events, Slack threads, custom webhooks, or schedules.
-
Test normal TypeScript. Add evals and unit tests without a separate configuration language.
-
Choose where it runs. Deploy to Cursor-managed hosting or run the process on your infrastructure.
When to use BDK
| Cursor Automations | Grok Bot | BDK | |
|---|---|---|---|
| Use for | Repeatable jobs driven by a prompt and a trigger | Interactive agents that work with you in Cursor | Agents that need custom code, integrations, tests, or deployment choices |
| You define | A prompt, model, and trigger in the dashboard | Instructions, skills, and connected tools in the app | A versioned Markdown and TypeScript project |
| Where it runs | Cursor-managed | Cursor-managed | Cursor-managed hosting or your infrastructure |
| Choose it when | The job fits a schedule or event trigger | You want an agent you can configure and talk to without creating a software project | You want deterministic code around model judgment and a project your team can review and test |
Architecture
Define the project in source control. Run execution, inference, and sandboxing on Cursor infrastructure or on your own host.
You bring the code and ideas
Agent as code
Prompts as .md or .ts
Deterministic code hooks
Cursor-managed or self-hosted
- Source control + Issue tracker + Slack triggers
- Model routing
- Evals
- MCP connections
- Sessions · Model loopsSubagents · Tool calls
- Secret management
- Sandboxing
- Deployment
- Storage + Artifacts
Get started
Install @cursor/bdk, then start with bdk init and bdk dev.
npm install --global @cursor/bdkbdk init ./my-botcd my-botbdk devOpen the project in Cursor. BDK projects use bot/.
my-bot/├── package.json├── bot/│ ├── agent.ts # model and local harness config│ ├── instructions.md # the system prompt│ ├── tools/│ │ └── approve_pr.ts # one typed tool per file│ ├── skills/│ │ └── pr-review/│ │ └── SKILL.md # procedures the model loads on demand│ ├── mcp-connections/│ │ └── linear.ts # tools from an MCP server│ ├── host-connections/│ │ └── inventory.ts # host-only MCP tools│ ├── subagents/│ │ └── verifier/│ │ ├── agent.ts│ │ └── instructions.md│ ├── channels/│ │ └── github.ts # wake on pull requests, CI, and comments│ └── hooks/│ └── audit.ts # observe session events└── evals/ └── readiness.eval.ts # regression checksDescribe your bot or agent in Cursor, or edit the files yourself.
Next steps
-
Build your first PR reviewer: a working GitHub reviewer, one step at a time.
-
Start from a template: Grok Bot agents, security reviewer, Thermo review, Thermo quality review, owners-policy approver, issue triager.
-
Convert a Cursor Automation: export an Automation from the dashboard into a project you own.
-
Export a Grok Bot: turn a recipe into a BDK project and review what needs manual setup.
-
Build agents with agents: hand the build to a coding agent with the package's bundled skills.
-
Project layout and CLI: every folder and every command.