Documentation Index
Fetch the complete documentation index at: https://docs.ironbee.ai/llms.txt
Use this file to discover all available pages before exploring further.
Project
A project maps to a codebase. When you runironbee 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:| Type | Description |
|---|---|
code_change | The agent edits one or more files |
verification | The agent runs a verification cycle |
fix | The agent makes corrections after a failed verification |
tool_call | A single tool invocation (browser navigation, screenshot, 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:- Navigate to affected pages
- Take screenshots
- Check browser console for errors
- Test functionality (clicks, forms, navigation)
- Submit a verdict
browser.verifyPatterns (most code file types). Disable it with ironbee browser disable.
Node cycle
The agent connects to a running Node.js process and:- Sets V8 tracepoints or logpoints at changed code paths
- Exercises those paths
- Reads back execution snapshots or runtime logs
- Submits verdict with backend evidence
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 withironbee 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:passorfail- Evidence fields: pages tested, console errors, network failures, backend probes (for Node cycle)
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 span chart in the console visualizes these as a waterfall diagram, 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
Monitoring-only mode
When verification is disabled (ironbee disable-verification), 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 — 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 two locations, deep-merged (project takes precedence):| File | Scope |
|---|---|
~/.ironbee/config.json | Global — applies to all projects |
<project>/.ironbee/config.json | Project-level — overrides global |