Skip to main content
IronBee’s core idea is simple: code isn’t done until it’s verified. This page explains the mechanism behind that: how IronBee intercepts task completion, what the agent has to do to pass, and what happens when it doesn’t.

​
The completion gate

When you run ironbee 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:
CycleExercises the change through…
BrowserA real browser, navigation, screenshots, console, accessibility
NodeThe Node.js V8 inspector, probes, runtime snapshots, and outbound HTTP capture
PythonA running Python process over debugpy/DAP, probes, thread dumps, and outbound HTTP capture
BackendReal protocol calls HTTP, gRPC, GraphQL, WebSocket
AndroidAn emulator over ADB taps, swipes, screenshots, UI snapshots, Logcat, HTTP capture
TerminalA pseudo-terminal (PTY) spawn the CLI / REPL / TUI, send input, capture output and exit codes
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",
  "checks": [ ... ],
  "issues": [ ... ],
  "fixes":  [ ... ]
}
IronBee doesn’t take 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. The maxRetries 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 dedicated ironbee-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.

​
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-verify command, 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 with ironbee 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-session sessions/<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.