Codex Usage Widget Publish

Install, update, inspect, or uninstall a local-only Uebersicht 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, Uebersicht 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 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:

bash

scripts/install.sh

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

text

~/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:

bash

scripts/uninstall.sh

This removes only:

text

~/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:

bash

python3 "$HOME/Library/Application Support/Uebersicht/widgets/codex-usage.widget/codex-usage.py"

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