> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironbee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Cursor
> How IronBee integrates with Cursor - slash commands, rules, hooks, tools, and MCP activation.
When you run `ironbee install` in a project where [Cursor](https://cursor.com) is detected, IronBee writes the hooks, rules, and tools Cursor needs to verify your agent's work. The integration mirrors [Claude Code](/cli/clients/claude-code), with a few Cursor-specific details, including one manual step to activate the MCP server.
***
## What gets installed
| File | What it does |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.cursor/hooks.json` | Registers IronBee's lifecycle hooks |
| `.cursor/skills/ironbee-verification.md` | The verification skill the agent follows |
| `.cursor/skills/ironbee-verify/SKILL.md` | The `/ironbee-verify` command |
| `.cursor/skills/ironbee-{manage,search,sync}-scenario/SKILL.md` | The [saved-scenario](/cli/guides/scenarios) commands (the main agent drives the scenario tools — Cursor has no sub-agent) |
| `.cursor/rules/ironbee-verification.mdc` | An always-applied rule (`alwaysApply: true`) |
| `.cursor/mcp.json` | The devtools MCP server — a single **`ironbee-devtools`** entry that serves every enabled cycle's tools (`bdt_*` / `ndt_*` / `pdt_*` / `bedt_*` / `adt_*` / `tdt_*`) |
| `.cursor/permissions.json` | An allowlist so the agent isn't prompted on every devtools call or `ironbee` command (a single `ironbee-devtools:*` + `ironbee` in the terminal allowlist) |
These are merged into your existing Cursor config, not overwritten.
Unlike Claude Code and Codex, Cursor **doesn't use a verifier sub-agent** — the main agent drives the devtools tools directly. (Cursor's sub-agents run in a separate conversation that can't share the verification session, so there's nowhere to delegate to.) The [`verification.model`](/cli/configuration/configuration#verification) setting is therefore a no-op for Cursor.
***
## Activate the MCP server
Cursor sometimes doesn't pick up MCP servers added via `mcp.json` automatically. After installing, you usually need to activate it by hand.
After running `ironbee install`:
1. **Restart Cursor** so it loads the new hooks and MCP config.
2. Go to **Settings → Tools & MCP** and confirm the **`ironbee-devtools`** server is listed and on (it carries the tools for every cycle you enabled).
3. If the server shows as enabled but its tools aren't available, toggle it off and back on.
This is a known Cursor limitation: MCP servers added via config sometimes need a manual nudge.
***
## Slash commands
The `/ironbee-verify` command from Claude Code is available in Cursor too:
* **`/ironbee-verify`** run a verification cycle for the current changes. You can pass a **custom scenario** — inline text or a path to a scenario file — that defines exactly what to verify; when supplied it replaces the default "exercise the changed paths" flow. An optional leading `fix` switches it from the default verify-only behavior into a fix-and-re-verify loop — see [Verify-only vs. fix mode](/cli/guides/verification#verify-only-vs-fix-mode).
See [Claude Code → Slash commands](/cli/clients/claude-code#slash-commands) for the full breakdown; it behaves the same in Cursor, except Cursor's main agent runs the verification itself rather than delegating to a sub-agent.
***
## How verification is enforced
Cursor's stop hook can't hard-deny completion the way Claude's can, so IronBee uses Cursor's `followup_message` mechanism: when verification fails, it auto-submits a new prompt that pushes the agent back into the verification loop, mechanically preventing the task from finishing until it passes (up to Cursor's `loop_limit`, default 5).
Restart Cursor after installing, and remember the MCP activation step above; without it the agent won't have the devtools tools it needs to verify.
Cursor can also power IronBee's **LLM suggestions** — the `s` "suggest" key in the install platform picker and the [`ironbee checks suggest`](/cli/guides/verification#let-ironbee-suggest-your-checks) command — by running a one-shot headless prompt via `cursor-agent`. When Claude Code or Codex is also present, IronBee prefers those (`claude > codex > cursor`).
***
## Session analytics
Like Claude Code and Codex, Cursor sessions ship **structural analytics** to the Collector (turns, tools, code-line counts, timings) plus per-request token and cost events. Cursor's pipeline is a little different under the hood: Claude and Codex read a transcript file with embedded token usage, but Cursor keeps its conversation in a local SQLite store (`state.vscdb`) that has the *structure* but **no token or cost data**. IronBee fills that gap from Cursor's own per-user **usage API** (`api2.cursor.sh`), joining the two by timestamp.
Because the token/cost half comes from that API, it's gated behind a capability you can turn off:
```bash theme={null}
ironbee cursor api-access status # show the flag, token readability, plan tier, and a live usage probe
ironbee cursor api-access disable # stop reading the token / calling the usage API
ironbee cursor api-access enable # re-enable (the default)
```
| State | What analytics carry |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **On** *(default)* | Full analytics — structure **plus** exact per-request tokens and cost (Cursor's own billed numbers) and rate-limit windows. |
| **Off / unavailable** | Structure + code-line analytics only; token and cost are omitted. |
To read tokens and cost, IronBee reads your local Cursor session token (from `state.vscdb`, falling back to the macOS Keychain) and calls the usage API. It never prompts for it, and the capability is the on/off switch for the whole behavior. It maps to the [`cursor.apiAccess.enable`](/cli/configuration/configuration#cursor-cursor-only) config key (with `cursor.apiAccess.usageTtlSeconds` tuning the fetch cache) and is the Cursor parity of Claude's [OAuth access](/cli/clients/claude-code#claude-oauth-access).
A few signals Cursor simply doesn't expose are always omitted — cache-creation tokens, skill usage, and the rolling 5-hour / 7-day rate-limit windows Claude reports. Cursor surfaces a monthly quota and a hard USD cap instead, which ride along in the generic rate-limit window map.
Cursor sessions are also backfilled by [`ironbee import`](/cli/guides/importing-sessions) — its "transcript" is the composer inside `state.vscdb`, so there's no per-session `.jsonl` file, but imported sessions land in the Console alongside live ones.
***
## What's next?
The same integration for Claude Code.
The same integration for Codex.