# Codex Quota Widget

> Install, configure, verify, troubleshoot, update, or remove the Codex Quota Widget on Windows. Use when a user wants a local PowerShell/WPF Codex Desktop quota HUD, five-color task-status lights, a 0-100% opacity slider with a zero-opacity recovery point, crash recovery, or Codex-scoped lifecycle startup.

- Skill: `liorzarek12-cmd/codex-quota-widget` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add liorzarek12-cmd/codex-quota-widget`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liorzarek12-cmd/codex-quota-widget/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: liorzarek12-cmd (https://skillmd.com/u/liorzarek12-cmd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liorzarek12-cmd/codex-quota-widget

---


# Codex Quota Widget

Manage the Windows-only widget shipped in this repository. Preserve the user's existing state and verify a visible result instead of treating process startup as success.

## Safety boundaries

- Require Windows 10/11, Windows PowerShell 5.1, WPF, and a signed-in Codex Desktop app.
- Never print, copy, commit, or retain values from `auth.json`. The widget reads the login token only in memory for the quota request.
- Treat `widget-state.json` and `widget-monitor-state.json` as local private state. Never publish or overwrite them during an update.
- Ask before registering or removing the lifecycle scheduled task. Directly launching the widget is reversible and does not require registration.
- Do not modify the sealed expand/collapse, clipping, positioning, or immediate-click animation functions unless the user explicitly requests an animation redesign.
- Reuse the user's chosen long-lived application directory. Do not install into a temporary clone.

## Workflow

1. Locate the repository root containing `CodexQuotaWidget.ps1` and this `SKILL.md`.
2. Run `scripts/Test-PublicBuild.ps1`. Stop if parsing, status monitoring, opacity, dimensions, or animation-duration checks fail.
3. If installing from a clone, copy the clean tracked files to the user's selected application directory. Preserve any existing local state files.
4. Start `LaunchWidget.vbs` and verify the actual desktop window is visible and responsive.
5. If the user approves Codex-scoped automatic startup, run `InstallLifecycle.vbs`. This follows Codex Desktop rather than Windows logon.
6. Verify the current setting persists after restart and report the exact application directory.

## User controls

- Drag the expanded panel or compact HUD to move it.
- Click `-` to collapse; single-click the compact HUD to expand; double-click it to focus Codex.
- Right-click to refresh quota, adjust opacity from 0% to 100% in 1% steps, toggle always-on-top, status alerts, and motion, change the refresh interval, or exit.
- At 0% opacity, right-click the small cyan recovery point to reopen the opacity slider. Left-click intentionally does nothing.

## Status meanings

| Color | State | Meaning |
|---|---|---|
| Blue | Working | A user Codex task is active. |
| Green | Complete | The active task completed successfully. |
| Amber | Needs input | Codex is waiting for a question, confirmation, or approval response. |
| Red | Failed | The task failed, was interrupted, or was aborted. |
| Gray | Offline | Quota data cannot currently be refreshed. |

The monitor reads only lifecycle and status events from user-owned rollout files. It performs large-log recovery in a separate process and uses UTF-8 byte offsets for incremental reads, so the WPF thread never scans the full history.

## Troubleshooting

- Run `scripts/Test-PublicBuild.ps1` first.
- If the window is missing but Codex is open, inspect `CodexQuotaLifecycle.ps1`, then restart only the lifecycle watcher.
- If status is stale, inspect `widget-monitor-state.json` metadata without displaying rollout contents or secrets.
- If the widget crashes or stops sending heartbeats, the lifecycle watcher should restart it with bounded backoff. A manual `x` or menu exit must remain suppressed until the next Codex session.
- Use `UninstallLifecycle.vbs` only when the user asks to remove automatic lifecycle management; it does not delete the widget files or local state.