Skip to main content
When you run ironbee install in a project where Codex CLI is detected, IronBee wires up the hooks, guidance, and tools Codex needs to verify your agent’s work. The integration mirrors Claude Code and Cursor, with a few Codex-specific details covered below.
IronBee supports the interactive Codex CLI (the TUI you get from running codex). The non-interactive codex exec mode is out of scope. Codex doesn’t fire hooks there, so there’s nothing for IronBee to gate on.

​
What gets installed

IronBee writes Codex’s active config per project (under <project>/.codex/) so each project gets its own hooks, MCP server, and verifier — no machine-global “last install wins”. These files are committed alongside your .claude/* and AGENTS.md.
FileWhat it does
<project>/.codex/hooks.jsonRegisters IronBee’s lifecycle hooks
<project>/.codex/config.tomlEnables Codex’s hook runtime ([features] hooks = true) and registers the verifier agent ([agents.ironbee-verifier])
<project>/.codex/agents/ironbee-verifier.tomlThe verifier sub-agent that runs the cycles. A single [mcp_servers.ironbee-devtools] block (serving every enabled cycle’s tools) lives here, scoped to the sub-agent
<project>/AGENTS.mdThe always-applied verification rule, written into an IronBee-delimited block (<!-- ironbee:start --> … <!-- ironbee:end -->)
<project>/.agents/skills/ironbee-verification/SKILL.mdThe verification skill the agent follows
<project>/.agents/skills/ironbee-verify/SKILL.mdThe $ironbee-verify skill you can invoke by hand
<project>/.codex/agents/ironbee-scenario.tomlThe scenario sub-agent for saved scenarios (registered like the verifier, with the same read-only sandbox)
<project>/.agents/skills/ironbee-{manage,search,sync}-scenario/SKILL.mdThe $ironbee-{manage,search,sync}-scenario skills
IronBee’s entries are merged into your existing Codex config and AGENTS.md. Your own hooks, MCP servers, and guidance outside the IronBee block are never touched. On uninstall, only the IronBee block and skills are removed. Your user-level ~/.codex/config.toml still applies — for example its top-level model.
The layout above is the default sub-agent delivery mode. In main-agent mode there’s no ironbee-verifier.toml — the ironbee-devtools MCP server is registered at the session level in config.toml and the skill/rule/command are inlined instead of delegating. See How verification is delivered.
Restart Codex after installing so it picks up the new hooks, guidance, and MCP servers. The first time, Codex shows a one-time “hooks need review” prompt (its safety gate for project-level hooks) — run /hooks to approve. IronBee writes [features] hooks = true for you; without it Codex parses hooks but never dispatches them.

​
The $ironbee-verify skill

Codex has no user-defined slash commands, so IronBee’s manual verification trigger is exposed as a skill you mention by name. Type $ironbee-verify in the Codex prompt to run a verification cycle for the current changes. As with /ironbee-verify in Claude Code, you can pass a custom scenario — inline text or a path to a scenario file — that defines exactly what to verify: 
$ironbee-verify                              # default — exercise the changed pages/endpoints
$ironbee-verify check that the cart total    # inline scenario
  recalculates after removing an item
$ironbee-verify ./scenarios/checkout.md      # a scenario file
When a scenario is supplied it is authoritative and replaces the default “exercise the changed paths” flow; the completion gate is unchanged. As in Claude Code, an optional leading fix switches the default verify-only run into a fix-and-re-verify loop ($ironbee-verify fix) — see Verify-only vs. fix mode. Only the invocation syntax differs from Claude Code.

​
How verification is enforced

IronBee registers a Stop hook that fires when the agent tries to finish a task. If code files changed, the hook runs verification automatically and blocks completion until every active cycle passes. By default, like Claude Code, Codex delegates verification to the ironbee-verifier sub-agent — the devtools tools are scoped to that agent (in <project>/.codex/agents/ironbee-verifier.toml), so the main conversation never carries the heavy devtools output. The verifier navigates the affected paths and submits a verdict; on failure the main agent fixes the issues and re-verifies, up to your maxRetries limit. You can pin the verifier’s model with verification.model.
Enforcement only blocks task completion in enforce mode (ironbee verification auto enable). In the default assist mode the verifier and $ironbee-verify are installed but nothing gates completion — see Verification modes.
Codex’s Stop hook returns a decision: "block" with a continuation reason, which pushes the agent back into the verification loop, the same enforcement semantics as Claude Code. Codex exposes file edits through its single apply_patch tool, so IronBee gates edits on that instead of Write/Edit. File changes are recorded per patch, with the operation (create / update / delete) read from the patch body.

​
How verification is delivered

By default Codex runs the cycle in the ironbee-verifier sub-agent (the sub-agent delivery mode), exactly like Claude Code — the devtools MCP server is scoped to that agent and the heavy output stays out of the main conversation. If Codex’s sub-agent machinery regresses, you can fall back to driving the tools from the main agent instead: 
ironbee codex verifier mode main-agent   # main agent drives the devtools tools directly
ironbee codex verifier mode sub-agent    # back to the default delegated verifier
ModeWhat changes
sub-agent (default)The ironbee-verifier custom agent owns the devtools tools (per-agent MCP in ironbee-verifier.toml); a slim delegation skill/rule/command tell the main agent to hand off. Heavy devtools output stays in the sub-agent.
main-agentNo verifier sub-agent. The ironbee-devtools MCP server is registered at the session level ([mcp_servers.ironbee-devtools] in config.toml) and the main agent drives its tools itself, with an inline (non-delegating) skill/rule/command — the same shape Cursor uses.
Switching re-renders the Codex client. The choice maps to the codex.verifier.mode config key; verification.model still applies in sub-agent mode and is a no-op in main-agent mode (there’s no sub-agent to spawn).

​
Codex-specific behavior

A few details differ from the other clients, all handled automatically:
  • No SessionEnd hook. Codex doesn’t expose one, so IronBee treats every Stop as a checkpoint and writes a session-end snapshot there (the Collector keeps the latest). Quitting Codex with /quit fires no hooks.
  • Interrupt recovery. Pressing Esc to interrupt the agent doesn’t fire a Stop hook in Codex (#22858). IronBee reconciles the interrupted activity on your next prompt, so the session timeline stays accurate.
  • Sandbox grant for external runtime. With the default external runtime location, per-session data lives at ~/.ironbee/projects/ — outside the Codex workspace sandbox. So the agent’s verdict writes (ironbee hook submit-verdict / record-fix) don’t hit an approval prompt, IronBee adds a narrow [sandbox_workspace_write].writable_roots grant for ~/.ironbee/projects to config.toml (the global config.json and collector credentials under ~/.ironbee stay out of reach). It’s reconciled away in in-project or monitoring mode and removed on uninstall.
  • Config is project-level. Hooks, the MCP server, and the verifier are written per project (<project>/.codex/), so each repo gets its own setup and there’s no machine-global conflict. The devtools live inside the verifier agent (<project>/.codex/agents/ironbee-verifier.toml) under a single [mcp_servers.ironbee-devtools] block whose COMPOSE_PLATFORMS lists the enabled cycles — browser on by default, node / python / backend / android / terminal added when you enable those cycles. A model must be resolvable for the verifier sub-agent: it inherits your ~/.codex/config.toml model unless you pin verification.model; if neither supplies one, install warns you.
The Claude-only integrations — the statusline, OAuth access, and the local OTEL collector — don’t apply to Codex. Session lifecycle, tool calls, verdicts, and analytics still flow to the Collector.

​
What’s next?

Claude Code

The same integration for Claude Code.

Cursor

The same integration for Cursor.