Codex Usage Widget
Install, update, inspect, or uninstall a local-only Übersicht desktop widget that tracks Codex token usage, recent root sessions, source labels, and context-window pressure. Use when the user asks for a Codex usage widget, desktop usage monitor, Übersicht Codex monitor, local Codex session tracker, or help maintaining this widget.
Codex Usage Widget
What This Skill Provides
Use this skill to install or maintain a lightweight macOS Übersicht widget for Codex. The widget reads only local Codex files under ~/.codex:
state_5.sqlitefor thread metadata.logs_2.sqlitefor local log byte totals.sessions/**/*.jsonlandarchived_sessions/*.jsonlfor token-count events, origin labels, and context-window pressure.
It does not call external APIs, does not require a model key, and does not upload data.
Install
Run:
scripts/install.sh
The script copies assets/codex-usage.widget/ to:
~/Library/Application Support/Übersicht/widgets/codex-usage.widget/
Übersicht should refresh automatically. If it does not, use the Übersicht menu bar item to refresh all widgets.
Update
Run scripts/install.sh again. The script overwrites only this widget directory and does not touch Codex settings or other Übersicht widgets.
Uninstall
Run:
scripts/uninstall.sh
This removes only:
~/Library/Application Support/Übersicht/widgets/codex-usage.widget/
Behavior Notes
- Recent rows are grouped by root session, so spawned subagents do not appear as separate sessions.
- Source labels prefer rollout
originator:codex_vscodebecomesVSCode,Codex DesktopbecomesClient, and terminal/CLI-like originators becomeTerminal. - The right-side row metric is context-window pressure, calculated from the latest
input_tokens. It uses a 200K window until a session exceeds that level, then uses a 1M window. - The widget never parses message text. Recent rows are filtered only by Codex's local archived state and root-session relationships.
- The widget is intentionally best-effort because Codex local storage fields may change between Codex releases.
Validate
After installing, run:
python3 "$HOME/Library/Application Support/Übersicht/widgets/codex-usage.widget/codex-usage.py"
The command should print JSON with "ok": true.
- Downloads
- 742All time
- Security audit
- Pass
- Last updated
- 4mo ago
- Current version
- v1.1.0
- License
- MIT-0
