Install IronBee globally

npm install -g @ironbee-ai/cli

Cursor: additional setup

Cursor requires manual activation of MCP servers after install:

1. Restart Cursor to load the new hooks and MCP config
2. Go to Settings → Tools & MCP and verify each registered IronBee server is enabled — browser-devtools is always present on a default install; backend-devtools appears after ironbee backend enable; node-devtools appears after ironbee node enable
3. If a 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.

Quick Start

Usage

ironbee analyze <session-id>                    # single session analysis
ironbee analyze                                 # all sessions (project-level)
ironbee analyze --json                          # JSON output
ironbee analyze --detailed                      # include verdict details (checks, issues, fixes)
ironbee analyze --json --detailed               # JSON with verdict text for LLM semantic analysis
ironbee analyze <session-id> --json --detailed  # single session JSON with verdict details

The --detailed flag includes raw verdict text (checks, issues, fixes) in the output. This is designed for LLM-powered semantic analysis — use /ironbee-analyze in Claude Code or Cursor to have the agent interpret these details automatically.

Demo

https://github.com/user-attachments/assets/9d4e602b-6c05-4b48-89a8-3df429d10e00

Optional: backfill historical sessions

Already have weeks of Claude Code sessions on disk? ironbee import walks them and ships every session / activity / tool_call / file_change / analytics event to the IronBee Collector — so your dashboard fills with historical context the moment you finish installing. Already-tracked sessions (live or previously imported) are skipped automatically; pass --force to re-import.

Typical three-step flow:

```bash

3. Optional: cast a wider net later

ironbee import --all-projects --since 6m --concurrency 2 ```

--dry-run always shows the exact cost_usd that will surface in your dashboard before you confirm — $342.18 is much less surprising when you know it's coming.

Common scenarios

Flag groups

Scope (mutually exclusive — pick at most one; default is the current directory): - --transcript <path> — single .jsonl file - --projects <p1,p2,...> — comma-separated absolute project paths - --all-projects — every directory under ~/.claude/projects/

Time range (mutually exclusive; default is no filter): - --since <duration> — 30d, 2w, 6m, 12h (relative to now) - --from <iso-date> [--to <iso-date>] — explicit window; --to defaults to now

Behavior: - --dry-run — print summary, make zero POSTs, exit 0 - --yes — skip the confirm prompt - --force — bypass the "already tracked" skip rule - --concurrency <N> — parallel sessions (default 4, clamped to [1, 32]); also configurable via import.concurrency in ~/.ironbee/config.json or <project>/.ironbee/config.json

Optional: opt out of the browser cycle

ironbee browser disable

The browser cycle is the default-on cycle — every code-file edit (40+ extensions: .ts, .tsx, .css, .html, .py, .go, .java, …) requires browser-driven verification (navigate / screenshot / aria / console). Run browser disable for projects where you don't want browser-cycle enforcement (e.g. backend-only services where only backend enable / node enable apply). It writes browser.verifyPatterns: [] to override the legacy 40+ extension default; customizations of alwaysRequired / evidencePaths / additionalVerifyPatterns are preserved.

To re-enable: ironbee browser enable — strips the verifyPatterns: [] override so the code defaults (legacy 40+ extension list) flow back in at runtime. config.json stays minimal; the default list is NOT materialized into the file (it lives in code and tracks the CLI version automatically).

Optional: enable runtime-agnostic backend protocol verification

ironbee backend enable

Activates the backend protocol cycle — drives real HTTP / gRPC / GraphQL / WebSocket calls against your running backend service via the backend-devtools MCP (bedt_* tools) and verifies the responses. Works for any backend runtime: Node, Java, Python, Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin, Scala. The command writes a minimal { "backend": {} } block to config — code defaults (multi-language paths covering server/**, api/**, routes/**, controllers/**, handlers/**, services/**) flow in at runtime.

To revert: ironbee backend disable (drops the block clean if no customizations / lower-layer override; otherwise hard-kills via verifyPatterns: []).

Optional: enable Node.js runtime debug verification

ironbee node enable

Run this once per project whose backend is Node.js and you want IronBee to gate at the runtime level (V8 inspector probes via node-devtools). It writes a minimal { "node": {} } block to config — code defaults (e.g. server/**, pages/api/**, **/server.{ts,js,mjs,cjs}) flow in at runtime; nothing is materialized into the file. From then on, edits to matching paths require Node-cycle verification (connect + probes/logs) alongside any browser-cycle verification. To customize, set node.verifyPatterns (replaces defaults) or node.additionalVerifyPatterns (appends).

The node cycle is independent of the backend cycle — backend drives the wire protocol from outside, while node attaches to a Node.js process and sets non-blocking debug probes. Both can be enabled simultaneously; both must pass.

To revert: ironbee node disable. With no customizations the entire node block is dropped (clean config). With customizations or a lower-layer override, writes verifyPatterns: [] (hard kill, preserves alwaysRequired / evidencePaths / additionalVerifyPatterns so re-enabling later restores your tuned setup).

Optional: monitoring-only mode (no enforcement)

ironbee verification disable

Turns off enforcement but keeps the telemetry path intact. Session lifecycle and tool-call events still flow to the IronBee Collector, but the agent never sees a verify-gate, skill, rule, or /ironbee-verify command — useful when you want observability without slowing the agent down. To re-enable: ironbee verification enable.

The toggle re-renders all client artifacts (hooks, skill, rule, MCP servers, permissions) atomically. The change takes effect on the next agent session — restart your editor / agent after toggling.

Configuration

IronBee loads config from three layers and deep-merges them in order (each later layer overrides the earlier ones), then layers env-var overrides on top:

1. Global — ~/.ironbee/config.json
2. Project — <project>/.ironbee/config.json (committed; team-shared)
3. Project-local — <project>/.ironbee/config.local.json (gitignored; per-machine / per-developer override)
4. Env-var overrides — selected IRONBEE_* env vars (e.g. IRONBEE_API_KEY → collector.apiKey); env always wins over every file layer. See Env-var overrides below.

The local layer is optional — ironbee install adds .ironbee/config.local.json to .gitignore automatically, but the file is only created when you actually write to it (e.g. ironbee config set ... --local).

{
  "ignoredVerifyPatterns": ["*.test.ts", "*.spec.ts"],
  "maxRetries": 5,

  "browser": {
    "verifyPatterns": ["*.ts", "*.tsx", "*.css"],
    "additionalVerifyPatterns": ["*.mdx"]
  },

  "backend": {
    "verifyPatterns": ["routes/**/*.{go,py,java,ts}", "controllers/**/*.{go,py,java}"]
  },

  "node": {
    "verifyPatterns": ["server/**/*.ts", "pages/api/**/*.ts"]
  },

  "verification": {
    "enable": false
  },

  "fileChange": {
    "captureChangeset": true
  }
}

Editing config from the CLI (`ironbee config`)

You can edit any of the three config layers via the CLI instead of hand-rolling JSON:

```bash

Write to project config (default — committed, team-shared)

ironbee config set collector.url https://collector.example.com ironbee config set maxRetries 5 ironbee config set verification.enable false ironbee config set browser.verifyPatterns '[".ts", ".tsx", "*.css"]'

Write to global config (~/.ironbee/config.json)

ironbee config set collector.apiKey sk-... --global

Write to project-local config (<project>/.ironbee/config.local.json — gitignored, per-machine)

ironbee config set collector.url http://localhost:4000 --local

Env-var overrides

A small allowlist of IRONBEE_* env vars overrides specific config paths on top of the three file layers. Useful for secrets that shouldn't be committed (CI runners, ephemeral shells, multi-env desktop setups). Set to a non-empty string to override; unset or empty-string falls back to the file value. Env always wins over every file layer.

```bash

Devtools MCP server config

IronBee can register up to three MCP server entries from the same @ironbee-ai/devtools package (IronBee DevTools) — browser-devtools (bdt_ prefix, browser mode), backend-devtools (bedt_ prefix, runtime-agnostic backend mode), and node-devtools (ndt_ prefix, Node mode). Each is per-cycle gated (only enabled cycles get an entry) and can be customized independently via its own config block.

For the browser server, use browserDevTools:

{
  "browserDevTools": {
    "mcp": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

For the backend server, use backendDevTools:

{
  "backendDevTools": {
    "env": { "BACKEND_DEFAULT_HOST": "http://localhost:8080" }
  }
}

For the node server, use nodeDevTools:

{
  "nodeDevTools": {
    "env": { "NODE_INSPECTOR_HOST": "127.0.0.1" }
  }
}

You can mix-and-match: full config replacement via mcp, or just env-var additions via env. The two blocks below combine — one uses mcp for full replacement on the browser server, the other adds env vars to the backend server:

{
  "browserDevTools": {
    "mcp": {
      "command": "node",
      "args": ["./my-server.js"],
      "env": { "MY_VAR": "value" }
    }
  },
  "backendDevTools": {
    "env": { "OTEL_ENABLE": "true" }
  }
}

Note: IronBee always sets TOOL_NAME_PREFIX (bdt_ / bedt_ / ndt_), TOOL_INPUT_METADATA_ENABLE=true, and PLATFORM (browser / backend / node) — these cannot be overridden. When collector is configured, an OTEL exporter env block is also auto-injected on every server entry; operators can override individual OTEL_* keys via the env block above.