UsageAtlasBeta
Sign inGitHubOpen source
Codex

Codex statusline: show usage in your terminal

Put Codex token and limit information in your shell prompt or terminal status line. What is available natively, what needs a script, and a safe setup.

By UsageAtlas on

Quick answer

Codex does not ship a persistent status line of its own; the `/status` panel is shown inside the TUI. To see usage while the CLI is closed, run a small script that reads the latest session file and print the result in your shell prompt, or use UsageAtlas in the tray. Keep the script cached; parsing JSONL in every prompt is slow.

What Codex gives you natively

  • /status inside the TUI: model, context usage, session tokens.
  • The usage limits panel: both windows and reset times.
  • No exported status string for tmux, Starship, or Powerlevel10k.

That is deliberate. A status line that shells out to parse a growing JSONL file on every prompt adds latency to the one place you notice it most.

A safe pattern for a custom status

  1. Write a script that finds the newest file under ~/.codex/sessions.
  2. Extract only the last token count event with a streaming JSON parser.
  3. Cache the result to a small file for 30 to 60 seconds.
  4. Have your prompt read the cache, never the session log directly.
  5. Print a short string such as cx 42% wk 81%.
# pseudo-shell
cache=/tmp/codex-usage
if [ ! -f $cache ] || [ $(( $(date +%s) - $(stat -c %Y $cache) )) -gt 60 ]; then
  codex-usage-report > $cache
fi
cat $cache

The exact parser depends on your Codex version. Log the shape of one event first and code against that, rather than against a blog post.

The lower-effort option

If the goal is awareness rather than aesthetics, a tray icon is enough. UsageAtlas keeps both windows visible, updates in the background, and can fire one alert per reset cycle. It avoids adding work to your prompt entirely.

What a status line can and cannot show

A status line is a glance, not a report. It can show the current model, the context percentage, and the tokens used in this session. It cannot show the weekly total, the spend across projects, or the reset date of a window you are not in.

  • Use it to notice that context is filling up.
  • Do not use it to decide a plan change.
  • Keep the historical view in a tracker, not in the prompt.
  • Check Codex context window for what the percentage includes.

UsageAtlas keeps the history the status line cannot, with 7, 30, and 90-day ranges and the same token fields.

Questions, answered

Is there an official Codex statusline?

No. Codex shows usage in its own TUI panel. A status line in your shell requires a third-party script.

Will a statusline slow down my terminal?

It will if it parses session files synchronously on every prompt. Cache the value and refresh it on a timer instead.

Can a statusline show the weekly window?

Only if the script can read the reported limit state. Local session files show tokens, not the remaining weekly allowance.

Browse by topic