Codex Usage Widget

What This Skill Provides

Use this skill to install or maintain a lightweight macOS Uebersicht widget for Codex. The widget reads only local Codex files under ~/.codex:

• state_5.sqlite for thread metadata.
• logs_2.sqlite for local log byte totals.
• sessions/**/*.jsonl and archived_sessions/*.jsonl for 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.

For OpenClaw / Claw users, use this skill when the machine also runs Codex and the goal is to monitor Codex's local ~/.codex state from the desktop.

Install

Run:

scripts/install.sh

The script copies assets/codex-usage-widget/ to:

~/Library/Application Support/Uebersicht/widgets/codex-usage.widget/

Uebersicht should refresh automatically. If it does not, use the Uebersicht 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 Uebersicht widgets.

Uninstall

Run:

scripts/uninstall.sh

This removes only:

~/Library/Application Support/Uebersicht/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_vscode becomes VSCode, Codex Desktop becomes Client, and terminal/CLI-like originators become Terminal.
• 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.
• A root session can be hidden from the recent list after a standard wrap-up prompt plus a short user confirmation such as 23, all, no, or similar local-language variants.
• 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/Uebersicht/widgets/codex-usage.widget/codex-usage.py"

The command should print JSON with "ok": true.