# Bot Development Kit (BDK)

The Bot Development Kit (BDK) is how Cursor builds bots and
agents. It is the open-source version of the engine behind Bugbot,
Security Review, Approval Bot, and Rollouts.

A BDK project is a folder of Markdown and TypeScript. Combine model
judgment with deterministic code, then make the result available in
source control, Slack, issue trackers, and Cursor.

## Why use it

- **Bots and agents live in your repo.** Review, version, and ship
  instructions, tools, and evals with the rest of your code.

- **Cursor runs the loop.** Your project gets Cursor's models, tool
  calling, skills, MCP, and subagents.

- **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 trigger | Interactive agents you work with 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 without creating a software project | You want deterministic code around model judgment and a project your team can review and test |

## Get started

BDK requires Node 22.13 or newer. Install `@cursor/bdk`, create a
project, and start the development server:

```bash
npm install --global @cursor/bdk
bdk init ./my-bot
cd my-bot
bdk dev
```

For a one-off scaffold without a global install:

```bash
npx @cursor/bdk init ./my-bot
```

Open the project in Cursor. BDK uses `bot/` for the agent and keeps
`evals/` at the project root:

```text
my-bot/
├── package.json
├── bot/
│   ├── agent.ts
│   ├── instructions.md
│   ├── tools/
│   ├── skills/
│   ├── mcp-connections/
│   ├── subagents/
│   ├── channels/
│   ├── hooks/
│   └── schedules/
└── evals/
```

Describe the bot or agent in Cursor, or edit the files yourself.

## Start from a template

Pass a template to `bdk init` when one matches your goal:

| Template | Capability |
| --- | --- |
| `grokbot-agents` | Consult named Grok Bot agents |
| `security-reviewer` | Review pull requests for exploitable bugs |
| `thermo-quality-review` | Review structural code quality |
| `thermo-review` | Review bugs and breakage |
| `agentic-owners` | Apply owners policies to pull requests |
| `triage-linear` or `triage-jira` | Triage tracker issues |

```bash
bdk init ./security-reviewer --template security-reviewer
bdk init ./grokbot --template grokbot-agents
```

`--template triage` selects `triage-linear`.

## Next steps

Run `bdk docs` to open the full documentation. By default,
`bdk serve` also serves the same documentation at `/docs`.

The docs include:

- A complete PR reviewer quickstart
- GitHub, Slack, webhook, and MCP guides
- Evals and hillclimbing
- Deployment and troubleshooting
- Project layout, CLI, and API reference