The completion gate
When you runironbee install, IronBee registers a completion hook with your AI client (the Stop hook in Claude Code and Codex, the stop hook in Cursor). It fires when the agent tries to finish a task.
If the agent changed code files, the hook runs verification before letting the task complete:
If no code files changed (docs, config, etc.), the gate doesn’t trigger.
Verification cycles
A cycle is one pass of testing against a real surface. IronBee has six, and any combination can be active for a project:
When a task completes, every active cycle whose patterns match the changed files must pass in the same verification attempt. They run in parallel, not one task at a time. See Verification for choosing which cycles are active.
The verdict
To pass a cycle, the agent exercises the affected paths with that cycle’s tools and submits a verdict, its assessment of whether the change works:status: "pass" at face value. Each cycle defines the tools that must appear on the wire before a pass counts: required tools (all-of) and alternative evidence paths (any-of). If the agent claims success without actually using the tools, the gate overrides the verdict to fail. This is what stops an agent from declaring “it works” without testing.
Retries
A failed verdict sends the agent back to fix the issues and verify again. ThemaxRetries limit (default 3) caps this loop: once it’s hit, the agent is allowed to complete the task but must report the unresolved issues rather than silently pass. One counter covers all active cycles.
Who drives the tools
On Claude Code and Codex, the main agent doesn’t run the devtools tools itself — it delegates to a dedicatedironbee-verifier sub-agent that owns them. This keeps the heavy devtools output (DOM, console, screenshots) out of the main conversation while still recording everything to the same session. Cursor has no sub-agent surface, so its main agent verifies directly. See Verification → How verification runs.
Every agent-bound event the session ships — tool calls, file changes, verification start/end, verdicts, per-request cost — carries an agent_name (main for the top-level conversation, or the sub-agent’s name like ironbee-verifier), so the Console can show exactly who did what within one session. Each agent’s runtime state is likewise kept in its own partition on disk (see Runtime files → Per-agent state), so a delegated verifier and the main agent never race on the same files.
Default vs custom scenarios
By default the gate verifies only the areas affected by what changed. You (or the agent) can instead pass a custom scenario to/ironbee-verify — inline text or a path to a scenario file — to specify exactly which flows, states, and endpoints to exercise. See Custom verification scenarios.
Enforce, assist, and monitoring-only
The blocking gate described above is enforce mode. It’s one of three verification modes, and it’s opt-in — a fresh install defaults to assist:- Assist (default) (
ironbee verification auto disable) - the/ironbee-verifycommand, the verifier sub-agent, and the devtools MCP server stay installed so the agent (or you) can verify on demand, but no gate ever blocks completion. Every manual cycle is still recorded to the Collector. Turn on full enforcement withironbee verification auto enable. - Monitoring-only (
ironbee verification disable) - none of the machinery is installed. The agent works unblocked, but session lifecycle, tool calls, and timing still flow to the Collector. Useful for measuring baseline behavior before turning verification on.
Area-specific guidance
Teams can steer how the agent verifies a given part of the codebase by committing.ironbee/VERIFICATION.md files. When a change touches that area, IronBee injects the matching guidance into the agent’s context as it starts verifying: advisory instructions layered on top of the standard flow, resolved hierarchically from the changed paths.
Session isolation
Every agent task runs as its own session, tracked independently in a per-sessionsessions/<id>/ directory (by default under ~/.ironbee/projects/<token>/, outside the project tree — see Runtime files). Concurrent sessions, even in the same project, keep separate event logs, verdicts, and retry counters, so they never interfere. See Runtime files for what’s stored per session.
What’s next?
Manage Projects
Install, remove, track, and update IronBee across your projects.
Verification
Choose which cycles run and how enforcement behaves.