.ironbee/ directory inside each project, and a per-session runtime tree that by default lives outside the project. This page is a reference for what lives where, and what’s safe to commit.
Global (~/.ironbee/)
Machine-wide state, shared across all your projects:
| Path | What it holds |
|---|---|
config.json | Global config for your defaults across all projects. ironbee login writes your collector credentials here. |
projects.json | The project inventory, the set of project paths IronBee is installed in. Powers install --all / uninstall --all. |
install-snapshots.json | Backups of any statusline config IronBee overwrote, so uninstall can restore your original. |
projects/<token>/ | Per-session runtime data for each project, in the default external runtime location. <token> is derived from the project’s path, so each project gets its own folder. Holds the same sessions/<id>/ tree described below. |
Project (<project>/.ironbee/)
Created by ironbee install in each project:
| Path | What it holds | Commit? |
|---|---|---|
config.json | Project config, team settings, shared with the repo | ✅ Yes |
config.local.json | Personal overrides, your machine only | ❌ Gitignored |
scenarios/ | Saved verification scenarios — reusable, parametric test scripts authored via /ironbee-manage-scenario. A single flat store (older installs used per-cycle subfolders bdt/ndt/bedt/adt/tdt, still read for back-compat) | ✅ Yes |
VERIFICATION.md | Area-specific verification guidance, in any directory | ✅ Yes |
sessions/<id>/ | Per-session runtime data — only when runtime.location is in-project | ❌ Gitignored |
otel/ | Local OTEL collector daemon log (daemon.log) and raw OTLP bodies awaiting processing into session_context events. See OTEL collector. Always in-project, even in external mode | ❌ Gitignored |
ironbee install adds .ironbee/sessions/, .ironbee/otel/, and .ironbee/config.local.json to your project’s .gitignore automatically. These are machine-local runtime state and personal overrides, not something you commit. The committed config.json, scenarios/, and any VERIFICATION.md files are what your teammates pick up when they run ironbee install.
Where per-session data lives
The per-session runtime tree (sessions/<id>/) is controlled by runtime.location:
runtime.location | Per-session data lives at | Notes |
|---|---|---|
external (default) | ~/.ironbee/projects/<token>/sessions/<id>/ | Kept out of the project tree so a project never accumulates a growing sessions/ folder, even though it’s gitignored. <token> is a stable hash of the project’s real path. |
in-project | <project>/.ironbee/sessions/<id>/ | The legacy layout — runtime data sits beside your config, under the gitignored sessions/ folder. |
sessions/<id>/ are identical — only the base directory differs. Committed config (config.json, config.local.json, scenarios/, VERIFICATION.md) and the transient otel/ dir always stay in-project, regardless of runtime.location. Switch layouts with ironbee config set runtime.location in-project or the IRONBEE_RUNTIME_LOCATION env var; it takes effect on the next session.
Per-session (sessions/<id>/)
Each agent task gets its own directory, keeping concurrent sessions isolated (see How verification works):
| File | What it holds |
|---|---|
actions.jsonl | The session event log: file edits, tool calls, and verification markers. The source of truth for what happened. |
state.json | The session’s current state: phase, active cycle, verification status, and the project dir it belongs to. |
verdict.json | The latest verdict for the session (status, checks, issues, fixes). |
retries | The current verification retry count. |
analytics/ | Per-session analytics state (state.json) and log (analytics.log) used to derive session metrics. |
statusline/ | Chained-statusline state (state.json) for the Claude statusline integration. |
queue/ | Pending Collector jobs not yet shipped (and any dead-letter entries). See Job queue. |
session.log | Diagnostic log of the session’s hook activity. |
imported.json | A marker written by ironbee import so a session isn’t re-imported. |
Not every file is present in every session:
retries, queue/, and imported.json appear only when relevant. These persist after a session ends (they aren’t auto-deleted). You rarely touch them directly: use ironbee status to read verdicts and ironbee queue to inspect pending sends.What’s next?
Configuration
Every key you can set in the config files.
Environment variables
Overrides that take precedence over the config files.