codex-usage-statusline

A fast, zero-dependency companion statusline for OpenAI Codex that shows your model, project, branch, context window, and local 5-hour / 7-day usage with reset countdowns.

• 5h / 7d bars — fills as you consume each Codex rate-limit window
• Reset countdown — compact labels like reset 3h 40m or reset 3d 16h
• Local-session driven — reads Codex's own token_count events; no usage API call
• Privacy-aware by default — no full paths or thread titles in normal output
• Context bar — shows the latest turn's token usage against the model context window
• Color thresholds — green / yellow / red at 80 / 95 %
• Zero dependencies — pure Node, no npm install, no postinstall scripts

This is the Codex sibling to picoSols/claude-usage-statusline. Codex does not currently expose Claude Code's external statusLine.command hook, so this repo provides a companion terminal command plus the recommended native Codex TUI status-line config.

---

Install

git clone https://github.com/picoSols/codex-usage-statusline.git ~/.codex/codex-usage-statusline
cd ~/.codex/codex-usage-statusline
npm link

Then run:

codex-usage-statusline

Manual run without linking

node ~/.codex/codex-usage-statusline/statusline.js --plain

Native Codex Bottom Bar

Codex's built-in bottom status line uses named TUI items, not arbitrary shell commands. Add this to ~/.codex/config.toml:

[tui]
status_line = ["model-with-reasoning", "current-dir", "git-branch", "context-remaining", "task-progress"]
status_line_use_colors = true

Restart Codex after changing the config.

---

Requirements

• Node.js 18+
• Codex CLI with local session files under ~/.codex
• sqlite3 CLI recommended, but optional

If sqlite3 is unavailable, the command falls back to scanning the newest Codex session JSONL and prints whatever usage data it can infer.

---

Output

Codex | gpt-5.5/xhigh | my-project | main | pro
session 6.5M tokens | ctx [##------------] 13% 33.6k/258.4k last
5h [#-------------] 5% reset 3h 40m | 7d [#############-] 93% reset 3d 16h

The latest thread title is hidden by default. Add --show-title if you want it locally.

---

How it works

One tiny script:

File	Role
statusline.js	Reads Codex's local thread database and newest session JSONL, extracts the latest token_count event, and prints a compact usage summary.

The command reads:

• ~/.codex/state_5.sqlite for the latest thread, model, project, branch, and rollout path
• ~/.codex/sessions/**/*.jsonl for the latest token_count event

No network requests are made. Rate-limit values come from Codex's own local session events.

---

Configuration

Environment variables:

Var	Default	Effect
CODEX_HOME	~/.codex	Codex config/session directory
CODEX_STATE_DB	$CODEX_HOME/state_5.sqlite	Thread database path
CODEX_SESSIONS_DIR	$CODEX_HOME/sessions	Session JSONL directory
NO_COLOR	unset	Disables ANSI colors when set

CLI options:

Option	Effect
--plain / --no-color	Disable ANSI color output
--show-title	Include the latest Codex thread title in normal output
--json	Print a sanitized JSON snapshot
--raw-json	Print the full internal snapshot, including local paths and thread metadata
--help	Show help

---

Security

This tool is designed to be auditable in one sitting. The whole thing is a single dependency-free Node script.

What it touches

• Reads Codex's local thread database at ~/.codex/state_5.sqlite
• Reads Codex session logs under ~/.codex/sessions/
• Executes sqlite3 locally when available

What it does NOT do

• No telemetry, analytics, or phone-home
• No network calls
• No API-key or OAuth-token reads
• No writes to Codex config, session logs, or credentials
• No postinstall or lifecycle scripts
• No code loaded at runtime from outside this repo

Default output is sanitized for terminal use. Do not paste --raw-json output publicly without reviewing it.

---

Troubleshooting

No thread/project/model appears. Install sqlite3 or make sure it is on PATH. Without it, the command can still read the latest JSONL, but it may not know the current project or branch.

Rate limits are unavailable. Run a Codex turn first, then rerun the command. The tool needs a recent local token_count event.

The reset countdown says now. The local event did not include a future reset timestamp for that window, or the reset time has already passed.

I expected this to appear inside Codex automatically. Codex's native status line currently supports built-in item identifiers only. Use the [tui] config above for the bottom bar and run codex-usage-statusline as the richer companion command.

---

Contributing

Small, focused PRs welcome. Keep zero-dep, keep the script easy to read, and avoid adding background daemons or network calls.

License

MIT — see LICENSE.