/ironbee-verify, and nothing blocks completion.
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.
By default, IronBee counts a file as changed when the agent edits it with its file-editing tools. Edits made through shell commands, such as sed -i or a script, aren’t seen unless you set verification.changes.source to git. See How IronBee detects changes.
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 submits a pass without having used those tools, the gate rejects it and sends the agent back to verify. This is what stops an agent from declaring “it works” without testing.
A pass can still list issues. They are advisory: the change counts as verified, and the issues are reported for you to consider, not as something the agent must fix. Only a fail verdict’s issues have to be fixed.
name is an optional short label (3–6 words) for what the cycle actually verified. It isn’t part of the verdict itself: IronBee lifts it off the payload and stamps it on the cycle as it closes. See What a cycle records below.
What a cycle records
Beyond the verdict, every verification cycle carries three pieces of metadata so the Console can describe a run at a glance:Retries
A failed verdict sends the agent back to fix the issues and verify again. Two counters bound this loop, both capped bymaxRetries (default 3):
- The gate’s retry count, across all active cycles.
- The fail streak: consecutive failed verdicts for the current change. Each failed verdict’s reply shows it, for example
fail (2/3 for this change). The streak resets on a pass, on a not-applicable verdict, and whenever the gate lets the task complete.
RETRY LIMIT REACHED. The agent is then allowed to complete the task but must report the unresolved issues rather than silently pass. The streak also bounds delegated verification loops and manual /ironbee-verify fix runs, in every mode.
Who drives the tools
On Claude Code and Codex, the main agent delegates verification to a dedicatedironbee-verifier sub-agent that owns the devtools tools. This keeps the heavy devtools output (DOM, console, screenshots) out of the main conversation while still recording everything to the same session. On Codex 0.154 and later, the devtools server is also registered for the whole session, so the main agent can see its tools. IronBee’s rule, and in enforce mode its hook, keep the main agent delegating. 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, check results - 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.
Where sessions go
Every session reports to a project in the IronBee Console, where its verification cycles appear on the project’s Verifications tab. The project is chosen from your repository. See How IronBee identifies your project.What’s next?
Manage projects
Install, remove, track, and update IronBee across your projects.
Verification
Choose which cycles run and how enforcement behaves.