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
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, and the /ironbee-review command, which only you can run:
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: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.ironbee-review
Review your working tree withironbee review and report the findings. fix also fixes the blocking findings, fix loop reviews again after each fix pass, and price only asks what the review would cost:
disable-model-invocation: true in every mode, and the model never starts a review on its own. See From a coding agent for every mode and option.
Scenario commands
IronBee also installs/ironbee-manage-scenario, /ironbee-search-scenario, /ironbee-run-scenario, and /ironbee-sync-scenario for authoring, finding, running, 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.
ironbee-issue-track
When an issue tracker is connected (Jira, Linear, or GitHub Issues), install adds/ironbee-issue-track - read a ticket, verify your changes against its acceptance criteria, and report the evidence-backed result to the tracker. It delegates to its own ironbee-issue-tracker sub-agent. See Issue Tracking for the modes.
Assist mode: commands are user-only
In assist mode - which is manual-trigger-only by design - install marks every IronBee command (/ironbee-verify, the four scenario commands, and /ironbee-issue-track when present) with disable-model-invocation: true. You can still type them, but the model can’t auto-invoke them and their descriptions stop costing context tokens (they show as user-only in Claude’s /skills viewer). The sub-agents’ descriptions likewise switch to a non-proactive stance in assist mode, so the model doesn’t spawn the verifier or scenario agent on its own - a user-driven /ironbee-verify still spawns it explicitly. Enforce mode keeps auto-invocation on, since the verification mandate may route the model through the command. /ironbee-review is the exception: it’s user-only in enforce mode too.
Verification runs in a sub-agent
On Claude Code, the main agent does not drive the devtools tools itself. They’re scoped to a dedicatedironbee-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 - each tagged with its agent_name so the Console shows who did what.
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 fail streak reaches maxRetries, the reply reads RETRY LIMIT REACHED, and the agent reports the unresolved issues instead of looping. Issues listed on a pass verdict are advisory: only a fail’s issues have to be fixed.
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.
In-app view
The verifier works in a sub-agent, and Claude Code doesn’t stream a sub-agent’s output into your conversation. On Claude Code 2.1.287 and later, IronBee therefore draws its own view of the session inside Claude Code, so you can watch a verification while it runs.The line above the prompt
One line above the prompt, starting withIronBee, says where verification stands. It stays empty when there’s nothing to say:
In enforce mode the line says
✓ verified once the gate has accepted the pass, or when nothing the gate checks is still missing. Until then it reads ! pass submitted · the gate still wants …. A cycle that has recorded nothing for several minutes, typically one you interrupted, reads ! verification idle · no activity since 14:05. A verdict landing, or a scenario run ending, also raises a notification.
The /ironbee pane
Type/ironbee, or press Details on the line, to open the pane. In a wide fullscreen terminal it docks beside the transcript; otherwise it opens above the prompt. Now and Verdict are always there; Evidence appears once a run captured something, and Scenario after a scenario run:
Each screenshot is a row that unfolds its picture in the pane. kitty and Ghostty draw the real picture, outside tmux or screen and not over SSH. Every other terminal draws a low-resolution preview. Each item has a letter: on a screenshot it unfolds or folds the picture in the pane, and on any other file it opens the file outside the terminal.
o opens the unfolded screenshot at full size, and t opens the run in the IronBee Console.
The pane’s controls never send anything on their own. Verify, Re-verify and Verify & fix put /ironbee-verify or /ironbee-verify fix in the prompt for you to send, and Copy issues copies the verdict’s issues (Copy findings on a pass).
When the view appears
The view only displays what IronBee records. Verification works the same without it, and it never approves or blocks anything. You don’t get the view in these cases, and nothing else changes:- Claude Code is older than 2.1.287.
- The workspace isn’t trusted.
- The session runs in the VS Code panel, through
claude -p, or in the cloud. - Claude Code runs with
--safe-mode, or your organization’s settings block user mods or hooks. - The session started in a subdirectory of the project. Claude Code loads the view only from the session’s main working directory.
ironbee install writes the view into .claude/skills/ironbee/ and adds that folder to .gitignore. If the folder already holds a skill of your own, IronBee leaves it alone and skips the view. A re-install updates the view in place, and a running session picks up the change. If the view can’t read what an upgraded CLI prints, it shows a notification asking you to run ironbee install again. Monitoring-only mode and ironbee uninstall remove the view.
The view is on by default when install detects Claude Code 2.1.287 or later. Control it with claude.mod.enable, then re-run ironbee install:
true when you use the Claude Code desktop app, which ships its own copy of Claude Code that install can’t find. ironbee session view prints the same view in any terminal.
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 nextironbee install). Seeclaude.autoModeAllowlist.enable.
Workspace trust
Claude Code 2.1.x ignores a project’s committedpermissions.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
falseflag totrue, preserves every other entry and key in the file, and never creates~/.claude.jsonif 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. Seeclaude.trustWorkspace.enable.
Removed integrations
IronBee 0.42 removed the Claude-only insights integrations - the statusline wrapper (session_status events), the local OTEL collector daemon (session_context context-usage events), and the OAuth-token read (ironbee claude oauth-access) - along with the whole ironbee claude command group. Verification, session lifecycle, tool calls, file changes, verdicts, and VCS linkage are unaffected.
Upgrading cleans up after itself: the re-render restores whatever statusline you had before IronBee wrapped it (or strips ours so a lower settings layer re-emerges), removes the OTEL env block from settings.json, and deletes the transient .ironbee/otel/ directory. The statusLine.*, otel.*, and claude.oauthAccess.* config keys are inert and can be dropped from your config files.
What’s next?
Cursor
The same integration for Cursor.
Codex
The same integration for Codex.