Openclaw Skills lets you install and maintain a local-only Übersicht widget that tracks Codex token usage, root sessions, source labels, and context-window pressure on macOS.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install codex-usage-widget
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install codex-usage-widget using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Codex Usage Widget?
Openclaw Skills provides a privacy-first macOS Übersicht widget for monitoring Codex activity without leaving the machine. It reads local Codex artifacts under ~/.codex, aggregates session and token signals, and renders a compact desktop view of usage, recent root sessions, and context-window pressure.
Because it never calls external APIs, never needs a model key, and never uploads data, it is ideal for developers who want a lightweight local dashboard for Codex. Openclaw Skills is intentionally best-effort, so it stays aligned with Codex's local storage formats while remaining easy to install, update, validate, and remove.
Codex Usage Widget Use Cases
- Install a local Codex usage monitor on macOS with Übersicht.
- Inspect recent root sessions and token-count events without parsing message text.
- Distinguish usage sources such as VSCode, Client, and Terminal from local origin labels.
- Track context-window pressure at a glance to spot large or growing sessions.
- Update or reinstall the widget after a Codex or Übersicht change.
- Remove the widget cleanly without touching other widgets or Codex settings.
How Codex Usage Widget Works
- Run
scripts/install.shto copyassets/codex-usage.widget/into~/Library/Application Support/Übersicht/widgets/codex-usage.widget/. - Übersicht refreshes automatically; if it does not, use the menu bar item to refresh all widgets.
- The widget reads only local Codex files:
~/.codex/state_5.sqlite,~/.codex/logs_2.sqlite,~/.codex/sessions/**/*.jsonl, and~/.codex/archived_sessions/*.jsonl. - It groups recent rows by root session, so spawned subagents are folded into their parent session instead of appearing separately.
- It normalizes source labels from
originatormetadata and computes context-window pressure from the latestinput_tokens, using a 200K window until the session exceeds that level and then switching to 1M. - To maintain the widget, rerun
scripts/install.shfor updates, validate with the Python entrypoint, or runscripts/uninstall.shto remove only this widget directory.
Codex Usage Widget Setup
Requirements
- macOS with Übersicht installed
- Local Codex data available under
~/.codex - No API keys, model keys, or network configuration required
Install
scripts/install.sh
This copies assets/codex-usage.widget/ to ~/Library/Application Support/Übersicht/widgets/codex-usage.widget/. If Übersicht does not refresh automatically, use the menu bar item to refresh all widgets.
Validate
python3 "$HOME/Library/Application Support/Übersicht/widgets/codex-usage.widget/codex-usage.py"
A successful run should print JSON with "ok": true.
Update
scripts/install.sh
Uninstall
scripts/uninstall.sh
This removes only ~/Library/Application Support/Übersicht/widgets/codex-usage.widget/ and leaves other widgets and Codex settings untouched.
Codex Usage Widget Data Schema & Taxonomy
Input sources
| Path | Purpose | Notes |
|---|---|---|
~/.codex/state_5.sqlite |
Thread metadata | Used to understand thread and root-session relationships |
~/.codex/logs_2.sqlite |
Local log byte totals | Supports lightweight usage context |
~/.codex/sessions/**/*.jsonl |
Active session event stream | Supplies token-count events, origin labels, and pressure signals |
~/.codex/archived_sessions/*.jsonl |
Archived session event stream | Used for recent history and grouped rows |
Derived taxonomy
root_session: canonical grouping key that collapses spawned subagents under the parent session.source_label: normalized display label derived from rolloutoriginatorvalues, such ascodex_vscode->VSCode,Codex Desktop->Client, and terminal or CLI-like sources ->Terminal.context_window_pressure: computed from the latestinput_tokens; the widget uses a 200K window by default and switches to 1M once a session exceeds that boundary.recent_rows: best-effort local activity rows built from archived state only; the widget never parses message text.
Generated output
~/Library/Application Support/Übersicht/widgets/codex-usage.widget/— installed widget directory copied fromassets/codex-usage.widget/.- No external telemetry, API payloads, cloud exports, or long-lived derived database files are created by the skill.
Codex Usage Widget Advanced Features
- Local-only architecture with no external API calls, model keys, or uploads.
- Root-session aggregation that folds spawned subagents into one readable dashboard row set.
- Source-label normalization for fast recognition across VSCode, Codex Desktop, and terminal workflows.
- Adaptive context-window pressure scoring that changes from 200K to 1M when sessions grow.
- Non-destructive install, update, and uninstall scripts that only touch the widget directory.
- Best-effort compatibility designed to tolerate Codex local storage changes between releases.
- CLI validation via
codex-usage.pyfor quick post-install verification.
SKILL.md
Loading
Related Openclaw Skills
Memory Assistant
Openclaw Skills Memory Assistant turns daily notes into a searchable, long-term memory system for capturing context, finding past information, and consolidating durable knowledge.
SSL Cert Monitor
Openclaw Skills' SSL Cert Monitor audits domains for certificate expiry, chain integrity, and SNI problems, then produces cron-ready alerts and a status table.
Telegraph Protocol
Telegraph Protocol enables AI agents to query a decentralized marketplace for verifiable AI inference powered by transparent cryptographic micropayments.
YAML Config Validator
Openclaw Skills for YAML validation that catches Kubernetes, Docker Compose, and GitHub Actions errors before they break deployment.
Narodmon Daily Summary → Telegram
Automates daily Narodmon sensor reporting by fetching 24-hour readings, generating annotated charts, and sending them to Telegram.
Socrates Perspective
Socrates Perspective is an Openclaw Skills persona that turns the agent into a humble Socratic guide for probing assumptions, clarifying ideas, and deepening judgment.
Featured*
