Codex

Give Codex (the OpenAI coding agent, CLI or IDE) the Dungbeetle MCP tools so it can triage snapshot runs and — with your confirmation — approve baselines. You stay the account owner; Codex holds only a scoped, revocable agent token.

1. Prerequisites

• The Dungbeetle CLI: npm install -g dungbeetle.
• Node.js with npx (the server is on npm as dungbeetle-mcp — see Setup).
• A Dungbeetle cloud account with a repository (getting access).

2. Mint a token

dungbeetle login --label "Codex"

Approve the printed code at /ui/connect in your browser, picking the repository Codex may work with. See Agent authentication.

3. Configure MCP

Add to ~/.codex/config.toml:

[mcp_servers.dungbeetle]
command = "npx"
args = ["-y", "dungbeetle-mcp"]

[mcp_servers.dungbeetle.env]
DUNGBEETLE_AGENT_TOKEN = "dbat_…"

Self-hosting

Both commands default to the hosted cloud. On a self-hosted server, pass --server <url> to dungbeetle login and add DUNGBEETLE_SERVER_URL = "https://your-server" under [mcp_servers.dungbeetle.env].

Sandboxed / cloud environments

A sandboxed Codex run has no browser to complete the device flow, so inject the token as an environment secret (DUNGBEETLE_AGENT_TOKEN) in the environment's settings. Mint it beforehand: run dungbeetle login on a trusted machine, or start the login anywhere and approve the printed code from any signed-in browser — the code links the two.

Suggest the loop to the agent in your project's AGENTS.md:

## Snapshot testing

After editing UI or output-producing code, run `dungbeetle test`. If it fails,
read the semantic diff with the dungbeetle MCP tools (`dungbeetle_list_runs`,
`dungbeetle_get_run`) before changing baselines; baseline approval requires
human confirmation.

4. First loop

Ask Codex:

List the recent Dungbeetle runs and show me the semantic diff of the latest failed one.

Codex calls dungbeetle_list_runs, then dungbeetle_get_run with detail: "full" — a compact node-level diff, never screenshots. Fix the regression (or decide the change is intended), then:

Approve that run and promote the new baselines.

dungbeetle_approve_run is marked destructive — confirm it yourself before it runs; approval stays human-owned.

Scopes

Use the Triage preset (runs:read baselines:read analytics:read reviews:write) — the default when dungbeetle login requests no explicit scopes. Codex can read diffs and record your review decisions but can't push runs or rewrite baselines outside the promote-on-approve path. See scopes.