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

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

ironbee-review

Review your working tree with ironbee 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:
The main agent runs it in the conversation, without a sub-agent. A review spends your team’s credits, so the command carries 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 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 - 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 with IronBee, 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:
Set it to 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 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.

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.