Skip to main content
When you run ironbee install in a project where 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

FileWhat it does
.claude/settings.jsonRegisters IronBee’s hooks and the permissions the agent needs
.claude/skills/ironbee-verification.mdThe verification skill the agent follows (enforce mode)
.claude/rules/ironbee-verification.mdThe always-on verification rule that enforces the gate (enforce mode)
.claude/commands/ironbee-verify.mdThe /ironbee-verify slash command
.claude/commands/ironbee-{manage,search,sync}-scenario.mdThe saved-scenario slash commands
.claude/agents/ironbee-scenario.mdThe scenario sub-agent that authors, searches, and re-runs saved scenarios (like the verifier, it owns the scenario tools and can’t edit your code)
.claude/agents/ironbee-verifier.mdThe 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.jsonThe auto-mode allowlist carve-out 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 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: 
/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.
/ironbee-verify delegates to the ironbee-verifier sub-agent rather than verifying in the main conversation — see 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. 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 — for example ironbee verification model sonnet --client claude. See Verification → Picking the verifier’s 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 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 removes all IronBee permissions (and the verifier sub-agent) entirely. Assist mode 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.

​
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["<dir>"].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.

​
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. 
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.*.

​
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: 
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.*.

​
What’s next?

Cursor

The same integration for Cursor.

Codex

The same integration for Codex.