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 writes 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

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 file exist? — The agent must write a JSON verdict after testing.
4. Is the verdict valid? — Must include 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

{
  "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 errors array describing what went wrong:

{
  "status": "fail",
  "pages_tested": ["http://localhost:3000/dashboard"],
  "checks": ["form renders", "submit button unresponsive"],
  "console_errors": 2,
  "network_failures": 0,
  "errors": ["button click handler not firing", "TypeError in console"]
}

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