Key Concepts

​

Project

A project maps to a codebase, in practice usually a single git repository. When you run ironbee install in a directory, that directory is associated with a project in the console. All sessions, verifications, and analysis for that codebase are grouped under its project.

---

​

Session

A session is a single continuous working period for an AI agent from when it starts editing to when it completes (or is interrupted). Every agent task creates a session. Sessions record:

• All activities performed by the agent
• Every verification cycle attempted
• Total coding time, fix time, and idle time
• Pass/fail outcomes and retry counts

---

​

Activity

An activity is a discrete action within a session. Activities include:

• Code edits the agent makes to files
• Verification cycles the agent runs to test its changes
• Fixes the agent applies after a failed verification
• Individual tool calls (browser navigation, screenshots, API requests, console checks, etc.)

---

​

Verification cycle

A verification cycle (or just “cycle”) is one complete pass of testing. IronBee supports three cycle types that can run in parallel:

​

Browser cycle

The agent uses browser devtools to:

1. Navigate to affected pages
2. Take screenshots
3. Check browser console for errors
4. Test functionality (clicks, forms, navigation)
5. Submit a verdict

The browser cycle is on by default for code changes matching browser.verifyPatterns (most code file types). Disable it with ironbee browser disable.

​

Node cycle

The agent connects to a running Node.js process and:

1. Sets V8 tracepoints or logpoints at changed code paths
2. Exercises those paths
3. Reads back execution snapshots or runtime logs
4. Submits verdict with backend evidence

The Node cycle is opt-in enable it with ironbee node enable. Only applies to Node.js backends.

​

Backend cycle

The agent drives real HTTP, gRPC, GraphQL, or WebSocket calls against a running backend service and verifies the responses. Works with any backend runtime (Node, Java, Python, Go, Rust, and more). The backend cycle is opt-in enable it with ironbee backend enable. A single task can require multiple cycles in parallel the agent must provide evidence for each active cycle before completing.

---

​

Verdict

A verdict is the agent’s signed assessment of whether its changes work. It includes:

• status: pass or fail
• checks: evidence items the agent confirmed (e.g. “form submits successfully”, “API returns 200”)
• issues (on fail): what went wrong
• fixes (on a passing retry after a previous failure): what was changed to resolve the issues

IronBee validates the verdict against the evidence. If the evidence does not support a pass, the gate overrides to fail and the agent must retry.

---

​

Fix

A fix is a code change made by the agent in response to a failed verification. After a fix, the agent re-verifies. All fixes are tracked separately so you can see exactly what the agent changed to resolve an issue.

---

​

Trace & span

IronBee records traces for each verification cycle, a structured log of every tool call, with timing. Within a trace, each individual tool invocation is a span. The waterfall chart in the console visualizes these as a timeline, making it easy to see what the agent tested, in what order, and how long each step took.

---

​

Analysis

After a session completes, IronBee runs analysis an LLM-powered pass over the session data. Analysis produces:

• Findings — specific problems identified (errors, failures, inconsistencies)
• Recommendations — concrete suggestions for improving code quality or the verification setup

Analysis runs at two scopes: project level (focused on a single codebase) and account level (aggregated across all your projects, surfacing broader patterns).

---

​

Operation modes

IronBee supports three operation modes:

​

Assist mode (default)

Verification is enabled the devtools, the verifier, the /ironbee-verify command, and MCP servers are all installed but the completion gate does not automatically block the agent. The agent (or you) can run verifications on demand and the results are recorded, but a pass isn’t required before completing. This is the default after ironbee install — the tooling is available without strict enforcement.

​

Enforce mode

Verification is fully enforced. When the agent tries to complete a task, the completion gate triggers automatically and the agent cannot finish until all active verification cycles pass. Opt in with ironbee verification auto enable (or pick enforce at install time).

​

Monitoring-only mode

When verification is disabled (ironbee verification disable), IronBee runs in monitoring-only mode. The enforcement hook, verification skill, and MCP servers are not installed. Sessions still record tool calls and timing data and you get full observability without slowing the agent down. This is useful for measuring baseline agent behavior before enabling enforcement.

---

​

Projects inventory

ironbee install records every project it touches in ~/.ironbee/projects.json. This inventory powers batch operations like ironbee install --all (re-install across every registered project) and ironbee uninstall --all (wipe IronBee from every project). Use ironbee register / ironbee unregister for manual inventory management.

---

​

Config files

IronBee reads config from three locations, deep-merged (project-local wins over project wins over global): The IRONBEE_API_KEY environment variable overrides collector.apiKey from any config file. See Configuration for all available options.