Codex CLI Cost Tracking: Token Usage, Per-Session Cost, What's Missing
That is one real Codex session, priced: gpt-5.6-sol under a ChatGPT sign-in, 4 loop turns, 4 tool calls, 12¢ at API rates — and 98% of the tokens were the loop re-reading its own context, which is the number a token counter can never show you. Hooks alone never see tokens — they see tool calls. Metering the model calls used to mean hand-editing ~/.codex/config.toml. It is now one install and one launcher.
Just want the answer? Codex CLI doesn't price sessions. Install ACP, then start Codex with codex-acp instead of codex — same responses, every call priced:
curl -sf https://agenticcontrolplane.com/install.sh | bash
codex-acpPlain codex keeps its current provider. The installer writes the provider block shown below and never puts a key in config.toml. · Full Codex setup (both planes) → · free for individuals
OpenAI’s Codex — the Codex CLI and the Codex IDE extension — will happily spend money all day and never tell you how much. That’s not an oversight you’re missing a flag for — there is no built-in cost tracking, and the feature request for it (openai/codex #5085, an RFC for a full cost-and-usage module: real-time cost display, budgets, per-project attribution, export) was closed without shipping. A related ask, token/cost info in rollout files, is #3201.
This is the reference for what you can see natively, why it isn’t cost tracking, and the install that closes the gap.
What Codex shows natively
- Context-window usage in-session — the status line tracks how full the model’s context is. That’s a capacity gauge, not a bill.
- Token counts in rollout files — sessions leave records under
~/.codex/, and token information appears there in limited forms. Nothing prices them. - Your OpenAI dashboard — if you authenticate with an API key, usage lands in OpenAI’s billing views: aggregated by day and model, hours later, with no per-session, per-project, or per-agent attribution. If you sign in with a ChatGPT plan, there’s no meter at all — usage disappears into the subscription.
So the native answer to “what did that session cost?” is: wait for the invoice, subtract, guess.
Why token counts aren’t cost tracking
Three things a raw token counter can’t tell you, and per-call metering can:
- Dollars per session, at the moment they’re spent. A long
--full-autorun is exactly the case where nobody is watching — the cost of a runaway loop should surface while it’s running, not on next month’s statement. - Cache economics. Input tokens are not all priced equally — cached reads bill at a fraction of the full rate, so two sessions with identical token counts can differ several-fold in dollars. Whether your prompt prefix stays cache-stable across turns is invisible in a token total and obvious in per-call metering.
- Loop vs. leaf attribution. In agent sessions most spend is the orchestration loop re-reading its own context — across the June 2026 snapshot (210,840 calls) on our data page, roughly 89% of spend sat in the loop, not the leaf work. A token counter gives you one number; attribution tells you which part of the session to fix.
The install
curl -sf https://agenticcontrolplane.com/install.sh | bash
The installer detects Codex, registers the hooks and MCP connector for the control plane, and — when you connect a workspace rather than running --local — does two things for the cost plane:
- Writes the provider block into
~/.codex/config.toml(idempotent; it never sets it as the default, so plaincodexkeeps whatever provider it had). - Installs
codex-acp, a launcher that starts Codex with that provider selected for this one invocation (codex -c model_provider=acp, a documented Codex flag) and supplies your workspace key from~/.acp/credentialsthrough the environment. No key is ever written toconfig.toml.
Run codex-acp where you would have run codex. Each /responses call passes through the proxy using the authentication already selected in Codex: ChatGPT OAuth remains subscription traffic; an API-key login remains Platform-billed traffic. The usage fields on the way back are priced, and the call lands as a row — model, tokens, cached share, dollars — in the console. Sessions aggregate into runs, so you get per-session cost, not just per-call. The screenshot at the top is what that looks like for one codex exec run.
What the installer writes
For the record, or if you would rather edit by hand, this is the block. Two rules that cost people the most debugging time, both from Codex’s own source: the block must live in ~/.codex/config.toml — provider keys are ignored in project-local .codex/config.toml — and wire_api accepts only "responses" (Codex removed wire_api = "chat" in v0.96; the TOML deserializer hard-errors on it, discussion #7782).
# ~/.codex/config.toml
[model_providers.acp]
name = "Agentic Control Plane"
base_url = "https://api.agenticcontrolplane.com/openai/v1"
requires_openai_auth = true # preserve ChatGPT or API-key login
wire_api = "responses" # only legal value since v0.96
env_http_headers = { "x-acp-key" = "ACP_KEY" } # your ACP workspace key (gsk_...), from env
To make it the default for plain codex as well, add model_provider = "acp" at the top level and export ACP_KEY yourself. codex-acp exists so you don’t have to.
Workspace-managed API billing is still available, but only through an explicit workspace-billing configuration. ACP never silently falls back from a missing subscription credential to a stored workspace key.
Subscription and API-key billing
Current Codex custom providers can set requires_openai_auth = true, which attaches either the user’s ChatGPT OAuth credential or their selected Platform API key. ACP routes those modes to their corresponding OpenAI upstreams and records the mode on each call.
For subscription traffic, dollar figures are explicitly labelled as API-rate equivalents: they show what the same token usage would cost through the API, not an additional charge made by ACP. API-key traffic is billed by the user’s OpenAI Platform account at standard API rates.
Budget limits
Codex has none. Through the proxy, workspace-billed traffic is subject to your workspace’s daily LLM cost limit, enforced at the gateway before the call goes upstream. User-authenticated traffic—ChatGPT subscription or BYO API key—is billed or quota-limited by OpenAI; ACP meters it but cannot enforce the upstream account’s hard cap.
Troubleshooting
Provider config seems ignored. It’s in a project-local .codex/config.toml — provider keys only load from ~/.codex/config.toml. Move the block.
401 saying Codex sent no OpenAI authentication. Add requires_openai_auth = true to the ACP provider and confirm codex login status shows the intended ChatGPT or API-key login. ACP will not silently substitute a workspace key.
Hard error mentioning wire_api. You have wire_api = "chat" somewhere — removed in v0.96. The only legal value is "responses".
Provider id conflicts. openai, ollama, and lmstudio are reserved ids and can’t be overridden. Use acp (or anything else).
Calls work but nothing appears in the console. Check the x-acp-key header is actually reaching us: env_http_headers reads the ACP_KEY env var at launch. Without it the request is treated as unauthenticated and rejected — the proxy never silently meters to nowhere.
What this pairs with
Cost is one of the two planes. The other — controlling what Codex does — is the hook + MCP-connector layer covered in the Codex CLI hooks reference. They’re independent: hooks see tool calls and never token usage; the proxy sees model calls and never what your shell actually ran. Ways to set up ACP wires both and tells you which planes you have.
Frequently asked questions
Does Codex CLI track cost?
Not in dollars. The CLI surfaces token counts (context-window usage in the status line, token info in rollout files) but has no built-in per-session dollar cost, no historical spend view, and no budget limits. The demand is well documented — openai/codex #5085 is an RFC for exactly this module, closed without shipping — so cost visibility currently comes from outside the CLI.
How do I see what a Codex session actually costs?
Route Codex’s model calls through a metering proxy. The ACP installer writes the custom model provider into ~/.codex/config.toml and installs a codex-acp launcher; start Codex with codex-acp and every request/response is token-counted and priced per call as it happens. Plain codex is untouched; responses pass through unchanged.
Can I set a budget or spend limit for Codex CLI?
Not natively — the CLI has no budget controls. Through the ACP proxy, workspace-billed traffic gets a daily LLM cost limit enforced at the gateway. If you bring your own OpenAI key, billing happens upstream at OpenAI and ACP meters but cannot cap it — set the hard cap in your OpenAI dashboard in that case.
Does routing Codex through a proxy change model responses?
No. The proxy is a passthrough for the Responses API over SSE — same request upstream, same stream back. It reads the usage fields to price the call and forwards everything else untouched.
Does this work with a ChatGPT plan (subscription) sign-in?
Yes. Set requires_openai_auth = true on the ACP provider. Codex attaches the active ChatGPT OAuth or API-key login, and ACP routes it to the matching OpenAI upstream without changing the user’s billing mode. Subscription cost figures are labelled as API-rate equivalents, not extra charges.
Why does my custom provider config get ignored?
Provider keys are ignored in project-local .codex/config.toml — the [model_providers] block must live in ~/.codex/config.toml. Also check the provider id: openai, ollama, and lmstudio are reserved and cannot be overridden.
Where to read more
- Codex CLI hooks reference — the control plane: hooks.json, PreToolUse, what’s covered and what isn’t
- Ways to set up ACP — every stack’s setup path, ending with your coverage state
- Claude Code cost tracking reference — the sibling reference for Claude Code
- The loop tax — why ~89% of agent spend sits in the orchestration loop
- The Tool Surface Index — Codex’s 17 declared tools next to Claude Code’s 76
- OpenAI Codex config docs — canonical upstream reference for config.toml