IronBee CLI

The CLI for IronBee — The Verification Layer for Agentic Development

IronBee ensures that AI agents verify their code changes before completing a task. When an agent edits code, it cannot finish until it navigates to the affected pages, functionally tests the changes, and submits a passing verdict.

No more "it should work" — every change is tested.

Powered by browser-devtools-mcp — the agent navigates pages, clicks buttons, fills forms, takes screenshots, checks console errors, and writes a structured verdict.

Supported Clients

Quick Start

Install IronBee globally

npm install -g @ironbee-ai/cli

Set up a project

cd your-project
ironbee install

This auto-detects your AI client and writes:

• Hook configuration (so the client calls IronBee automatically)
• Verification skill/rules (so the agent knows the workflow)
• MCP server config (so the agent has browser access)
• Browser-devtools permissions

Cursor: additional setup

Cursor requires manual activation of the MCP server after install:

1. Restart Cursor to load the new hooks and MCP config
2. Go to Settings → Tools & MCP and verify browser-devtools is enabled
3. If the server shows as enabled but tools are unavailable, toggle it off and on

Note: This is a known Cursor limitation — MCP servers added via mcp.json may need manual activation.

That's it

The next time your AI agent edits code, IronBee will require browser verification before the task can complete.

Commands

ironbee install [project-dir] [--client <name>]   Set up hooks and config
ironbee uninstall [project-dir] [--client <name>] Remove hooks and config
ironbee status [project-dir]                      Show verdict status for active sessions
ironbee verify [session-id]                       Dry-run verdict validation

Configuration

IronBee loads config from two locations (project overrides global):

• Global: ~/.ironbee/config.json
• Project: <project>/.ironbee/config.json

{
  "verifyPatterns": ["*.ts", "*.tsx", "*.css"],
  "additionalVerifyPatterns": ["*.mdx"],
  "ignoredVerifyPatterns": ["*.test.ts", "*.spec.ts"],
  "maxRetries": 5
}

Default verify patterns

By default, IronBee requires verification for common code file extensions: .ts, .tsx, .js, .jsx, .css, .scss, .html, .py, .go, .rs, .java, .vue, .svelte, and many more.

Non-code files like README.md, package.json, or .gitignore do not trigger verification.

Verification Flow

When the agent tries to complete a task, IronBee runs these checks:

1. Were code files edited? — If no matching files were changed, the agent completes normally.
2. Were browser tools used? — The agent must have called: navigate, screenshot, accessibility snapshot, and console check.
3. Does a verdict exist? — The agent must submit a verdict via ironbee hook submit-verdict after testing.
4. Is the verdict valid? — Must include session_id, status, pages_tested, checks, console_errors, and network_failures.
5. Pass or fail? — Pass allows completion. Fail blocks the agent and asks it to fix the issues and re-verify.
6. Retry limit — After maxRetries failed attempts (default 3), the agent is allowed to complete but must report unresolved issues.

Verdict format

Verdicts are submitted via echo '<json>' | ironbee hook submit-verdict:

{
  "session_id": "<your-session-id>",
  "status": "pass",
  "pages_tested": ["http://localhost:3000/dashboard"],
  "checks": ["form submits successfully", "new item appears in list"],
  "console_errors": 0,
  "network_failures": 0
}

On failure, include an issues array describing what went wrong:

{
  "session_id": "<your-session-id>",
  "status": "fail",
  "pages_tested": ["http://localhost:3000/dashboard"],
  "checks": ["form renders", "submit button unresponsive"],
  "console_errors": 2,
  "network_failures": 0,
  "issues": ["button click handler not firing", "TypeError in console"]
}

On pass after a previous fail, include a fixes array describing what was fixed:

{
  "session_id": "<your-session-id>",
  "status": "pass",
  "pages_tested": ["http://localhost:3000/dashboard"],
  "checks": ["form submits successfully", "new item appears in list"],
  "console_errors": 0,
  "network_failures": 0,
  "fixes": ["reattached click handler to submit button", "fixed TypeError in event handler"]
}

The agent must submit a verdict after every verification attempt — both pass and fail. File edits are blocked until a verdict is submitted after using browser tools.

Session Isolation

Each AI session gets its own directory under .ironbee/sessions/<session-id>/:

.ironbee/sessions/<session-id>/
  actions.jsonl    # Event log (file edits, tool calls, verification markers)
  verdict.json     # Written by agent after verification
  retries          # Retry counter
  session.log      # Debug log

This means parallel sessions (e.g., multiple Claude Code instances) don't interfere with each other.

Development

npm install
npm run build       # Compile TypeScript
npm run lint        # ESLint
npm run test        # Jest (unit + integration + client tests)
npm run dev         # Run via ts-node

License

MIT