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

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.