Runtime Files

IronBee stores its state in a few places: a global directory in your home folder, an .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 — one `<name>.json` per scenario, plus a sibling `<name>.cache.json` holding a step-ful scenario’s captured `llm-action` replay scripts (both committed; never hand-edit the cache). A single flat store (older installs used per-cycle subfolders `bdt`/`ndt`/`pdt`/`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.

Either way the contents of 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
`state.json`	The session’s current state: phase, verification status, and the project dir it belongs to.
`agents/<agentId>/`	Per-agent state — see below. Each agent active in the session (the main conversation and every delegated sub-agent) gets its own partition.
`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/`	Queue snapshots awaiting delivery, dead-letter entries, and the worker log. 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.

Per-agent state (`agents/<agentId>/`)

A session usually has more than one actor: the main agent, and the delegated sub-agents IronBee installs (ironbee-verifier, ironbee-scenario, ironbee-issue-tracker). Everything an individual agent writes is partitioned under its own agents/<agentId>/ directory so concurrent writers — say a verifier running in the background while the main agent keeps working — never clobber each other’s state. The <agentId> is the host’s opaque agent/thread id (only the main conversation is literally main); the human-readable agent name travels separately, as cycle.json’s owner and the agent_name on shipped events.

File	What it holds
`actions.jsonl`	That agent’s event log: file edits, tool calls, and verification markers. The main conversation writes `agents/main/actions.jsonl`.
`cycle.json`	The agent’s one open verification cycle (id, kind — gated or scenario — start time, trace id).
`verdict.json`	The agent’s latest verdict (`status`, `checks`, `issues`, `fixes`).
`aux.json`	Auxiliary cycle flags (recording, conclusive checks, context injection, the scenario pause marker).
`steps.json`	The open scenario step stack.
`queue/jobs.jsonl`	The agent’s live Collector queue producer file.
`fix.json`	(main only) The active fix cycle and the `/ironbee-verify fix` intent.

Not every file is present in every session, and these persist after a session ends (they aren’t auto-deleted). Sessions from older CLI versions kept actions.jsonl at the session root — that file is still merged in for a session in flight across the upgrade, but new writes all land under agents/ (a pre-upgrade root verdict.json is no longer read; verdicts are looked up only under agents/<agentId>/). You rarely touch any of this directly: use ironbee status to read verdicts and ironbee queue to inspect pending sends.

Introduction

Concepts

CLI

GitHub Action

Help

Global (`~/.ironbee/`)

Project (`<project>/.ironbee/`)

Where per-session data lives

Per-session (`sessions/<id>/`)

Per-agent state (`agents/<agentId>/`)

What’s next?

Configuration

Environment variables

​Global (~/.ironbee/)

​Project (<project>/.ironbee/)

​Where per-session data lives

​Per-session (sessions/<id>/)

​Per-agent state (agents/<agentId>/)

​What’s next?

Configuration

Environment variables

Global (`~/.ironbee/`)

Project (`<project>/.ironbee/`)

Where per-session data lives

Per-session (`sessions/<id>/`)

Per-agent state (`agents/<agentId>/`)

What’s next?