> ## 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.
# Claude Code
> How IronBee integrates with Claude Code - slash commands, rules, hooks, tools, OAuth access, and the OTEL collector.
When you run `ironbee install` in a project where [Claude Code](https://docs.anthropic.com/en/docs/claude-code) is detected, IronBee writes everything Claude needs to verify your agent's work. This page covers what gets installed and the agent-facing commands.
***
## What gets installed
| File | What it does |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.claude/settings.json` | Registers IronBee's hooks and the permissions the agent needs |
| `.claude/skills/ironbee-verification.md` | The verification skill the agent follows (enforce mode) |
| `.claude/rules/ironbee-verification.md` | The always-on verification rule that enforces the gate (enforce mode) |
| `.claude/commands/ironbee-verify.md` | The `/ironbee-verify` slash command |
| `.claude/commands/ironbee-{manage,search,sync}-scenario.md` | The [saved-scenario](/cli/guides/scenarios) slash commands |
| `.claude/agents/ironbee-scenario.md` | The **scenario sub-agent** that authors, searches, and re-runs [saved scenarios](/cli/guides/scenarios) (like the verifier, it owns the scenario tools and can't edit your code) |
| `.claude/agents/ironbee-verifier.md` | The **verifier sub-agent** that actually runs the cycles. A single **`ironbee-devtools`** MCP server — it serves every enabled cycle's tools (`bdt_*` / `ndt_*` / `pdt_*` / `bedt_*` / `adt_*` / `tdt_*`) under one entry — is rendered **inline** into this file so it's scoped to the sub-agent. It also gets read-only `Read` / `Grep` / `Glob` (to understand the change) but **no edit tools** |
| `.claude/settings.local.json` | The [auto-mode allowlist carve-out](#auto-mode-and-the-verifier) for the verifier — written only when verification is active and `claude.autoModeAllowlist.enable` isn't `false`. Merged into any existing local settings |
These are merged into your existing Claude settings, not overwritten.
The `ironbee-devtools` MCP server lives inside the verifier sub-agent (above), not in a top-level `.mcp.json`. See [Verification runs in a sub-agent](#verification-runs-in-a-sub-agent) below.
Restart Claude Code after installing so it picks up the new hooks, commands, and MCP server.
***
## Slash commands
IronBee installs the `/ironbee-verify` slash command, which the agent (or you) can invoke directly in Claude Code:
### ironbee-verify
Run a verification cycle for the current changes. By default it exercises the areas affected by what changed. You can also pass a **custom scenario** describing exactly what to verify — either inline or as a path to a file:
```bash theme={null}
/ironbee-verify # default — exercise the changed pages/endpoints
/ironbee-verify log in as admin, open /billing, # inline scenario — verify exactly this flow
and confirm the invoice total updates
/ironbee-verify ./scenarios/checkout.md # a scenario file (any location, any format)
```
When a scenario is supplied it is **authoritative**: it replaces the default "exercise the changed pages" guidance, and the verifier drives precisely the flows, states, and endpoints it names. A scenario *file* is read at run time, so you can keep reusable test scripts in your repo. The completion gate is unchanged — every active cycle's required tools must still run for a `pass`.
An optional leading word picks what happens on a fail: the default is **verify-only** (report the verdict and stop), while a leading `fix` makes the agent fix the issues and re-verify until it passes — `/ironbee-verify fix`. See [Verify-only vs. fix mode](/cli/guides/verification#verify-only-vs-fix-mode).
`/ironbee-verify` **delegates to the `ironbee-verifier` sub-agent** rather than verifying in the main conversation — see [Verification runs in a sub-agent](#verification-runs-in-a-sub-agent).
### Scenario commands
IronBee also installs `/ironbee-manage-scenario`, `/ironbee-search-scenario`, and `/ironbee-sync-scenario` for authoring, finding, and repairing [saved verification scenarios](/cli/guides/scenarios). Like `/ironbee-verify`, they delegate to a dedicated sub-agent (`ironbee-scenario`). They're installed in enforce and assist modes, alongside the verifier.
***
## Verification runs in a sub-agent
On Claude Code, the main agent does **not** drive the devtools tools itself. They're scoped to a dedicated `ironbee-verifier` sub-agent: a single `ironbee-devtools` MCP server — serving every enabled cycle — is rendered inline into `.claude/agents/ironbee-verifier.md`. When verification is needed — automatically at the gate, or manually via `/ironbee-verify` — the main agent **spawns the verifier**, which runs every active cycle's tools and submits the verdict, then hands back a short summary.
This keeps the heavy devtools output (DOM snapshots, console logs, screenshots) in the sub-agent's context instead of flooding the main conversation. The sub-agent shares the parent session, so its verification events, tool calls, and verdict all land in the same session timeline, and its token/tool usage is folded back into the session analytics.
By default the verifier runs on the **same model as the main conversation**. To pin it to a specific (e.g. cheaper or faster) model, set [`verification.model`](/cli/configuration/configuration#verification) — for example `ironbee verification model sonnet --client claude`. See [Verification → Picking the verifier's model](/cli/guides/verification#picking-the-verifier-model).
Codex delegates the same way (a per-project verifier agent). **Cursor** keeps the main agent driving the tools directly — its sub-agents can't share a session, so there's no verifier sub-agent there.
***
## How verification is enforced
IronBee installs a **Stop hook** that fires when the agent tries to finish a task. If code files changed, the hook runs verification automatically (spawning the verifier sub-agent, the equivalent of `/ironbee-verify`) and blocks completion until every active cycle passes. The verifier navigates pages, exercises the affected paths, and submits a verdict; on failure the main agent fixes the issues and re-verifies, up to your [`maxRetries`](/cli/configuration/configuration#core-options) limit.
When the agent fixes something after a failed verdict, it can record what it repaired with `ironbee hook record-fix` so the next passing verdict describes the fix. If it doesn't, IronBee fills in the `fixes` from the files that changed since the failure — so a delegated verifier that didn't author the edit never blocks on a missing fix description.
***
## Permissions
The permissions IronBee writes are scoped to what's actually active. When any cycle is enabled, it grants a single devtools permission, `mcp__ironbee-devtools__*` — the one compose server carries every enabled cycle's tools, matched against the verifier sub-agent's inline tools — plus `Bash(ironbee *)` for the agent's CLI calls. (Any stale per-cycle permissions from an older CLI, like `mcp__browser-devtools__*`, are stripped on every install.) Switching to [monitoring-only mode](/cli/guides/verification#verification-modes) removes all IronBee permissions (and the verifier sub-agent) entirely. [Assist mode](/cli/guides/verification#assist-mode-default) keeps the permissions, the verifier sub-agent, and its MCP server (so manual verification still works) but drops the always-on skill and rule.
***
## Auto mode and the verifier
Recent Claude Code releases (2.1.176+) ship an **auto mode** with a host-side "Content Integrity" classifier that inspects sub-agent hand-offs and prepends a security warning to ones it judges fabricated. It **false-positives** on IronBee's legitimate verdicts: the verifier's devtools calls happen earlier in the cycle and aren't re-shown in the hand-off summary the classifier reviews, so a real, evidence-backed verdict can look made-up to it.
To keep verification working under auto mode, IronBee writes **one narrow allowlist rule** into `.claude/settings.local.json`, keyed to the exact verdict-submission command. It relaxes **only** the Content Integrity check for that command — every other auto-mode protection (data exfiltration, production reads, self-modification, …) stays fully in force, and IronBee's own completion gate still independently confirms the required tools actually ran.
* Written **only** when verification is active (enforce or assist), and it's **inert** unless the host is actually in auto mode.
* Lives in `settings.local.json` (the local layer, gitignored), merges safely alongside anything else there, and is removed on uninstall or when you switch to monitoring-only.
* Opt out with `ironbee config set claude.autoModeAllowlist.enable false` (takes effect on your next `ironbee install`). See [`claude.autoModeAllowlist.enable`](/cli/configuration/configuration#claude-oauth-access-claude-code-only).
***
## Workspace trust
Claude Code 2.1.x **ignores a project's committed `permissions.allow`** — the `mcp__ironbee-devtools__*` and `Bash(ironbee *)` entries IronBee writes into `settings.json` — until the workspace is **trusted**. And once you've dismissed Claude's onboarding, the trust dialog no longer re-appears, so those entries would stay silently disabled and the agent would get prompted on every devtools or `ironbee` call.
To avoid that, `ironbee install` marks the project trusted in Claude Code's machine-global `~/.claude.json` (it flips `projects[""].hasTrustDialogAccepted` to `true`) when verification is active and the flag isn't already set.
* This is the **one machine-global file** IronBee writes — every other Claude artifact is a per-project `.claude/*` file.
* **Best-effort, idempotent, and non-clobbering:** it only ever flips a missing or `false` flag to `true`, preserves every other entry and key in the file, and never creates `~/.claude.json` if it's absent (Claude writes it on first run).
* It is **not** reverted on uninstall — un-trusting a workspace could surprise you if you rely on the trust elsewhere.
* Opt out with `ironbee config set claude.trustWorkspace.enable false`. See [`claude.trustWorkspace.enable`](/cli/configuration/configuration#claude-oauth-access-claude-code-only).
***
## Claude OAuth access
IronBee can read your Claude Code OAuth token (macOS Keychain or `~/.claude/.credentials.json`) to fill in statusline rate-limits for plans whose statusline JSON omits them, namely **team and enterprise**. It's **on by default** and Claude-only.
```bash theme={null}
ironbee claude oauth-access status # capability flag, token readability + expiry, live plan / rate-limit probe
ironbee claude oauth-access disable # stop reading the token
ironbee claude oauth-access enable # re-enable (and prime the macOS Keychain permission)
```
On macOS, `enable` reads the token right away so the Keychain permission prompt appears in your terminal. Choose **Always Allow** so later background reads don't re-prompt. Writes to the global config by default; `--project` / `--local` target other layers. Underlying keys: [`claude.oauthAccess.*`](/cli/configuration/configuration#claude-oauth-access-claude-code-only).
***
## OTEL collector
To derive context-usage metrics, IronBee runs a small **local OTEL collector daemon** that receives Claude Code's OTLP export and turns it into `session_context` events. One daemon serves every session on the machine, and it starts and reaps itself automatically, so you rarely touch it. When you need to:
```bash theme={null}
ironbee claude otel status # query the daemon's /health
ironbee claude otel stop # graceful shutdown
ironbee claude otel retry # re-process bodies that piled up during an outage (starts the daemon if needed)
ironbee claude otel run # run in the foreground (mainly an internal spawn target)
```
All accept `--port` (default `15986`) and `-p, --project`. Tuning lives under [`otel.*`](/cli/configuration/configuration#otel-collector).
***
## What's next?
The same integration for Cursor.
The same integration for Codex.