ghostroller/codex-usage-monit

codex-usage-monit

English · 简体中文

Codex usage monitoring, entirely in your terminal.

codex-usage-monit tracks Codex quota windows, reset times, reset credits, tasks, turns, models, locally observed token usage, and usage history. Run it as an interactive TUI, or use its non-interactive CLI to produce plain text or JSON for scripts, cron jobs, and CI.

It is local-first and terminal-native: no desktop application, browser, database, or listening port is required. The TUI works as a standalone process; an optional per-user background recorder can keep quota history continuous while the TUI is closed. Prebuilt binaries run on Windows, macOS, and Linux, including headless development servers over SSH.

TUI preview

Deterministically rendered from the integration-test fixture. The synchronization check in CI prevents this preview from drifting from the current TUI.

Highlights

• Account usage at a glance — See used/remaining percentages, all available quota buckets, and server-reported reset times.
• Reset-credit details — See the authoritative available count plus grant and expiry times when the server returns per-credit details.
• Expiry reminder — The weekly Overview gauge warns when the earliest fully known available reset credit expires before the ordinary Codex weekly reset, with the exact local expiry time.
• Local usage breakdown — Explore tasks, turns, models, token totals, and token share for the current 5-hour or weekly reset cycle.
• Usage trends — Record server remaining quota, weekly local tokens, low-confidence weekly estimates, and 30-minute token/estimate buckets in local state.
• Optional background recorder — Keep collecting while the TUI is closed with launchd, systemd user services, or Windows Task Scheduler; no administrator account is required.

• Interactive terminal UI — Filter, search, switch scopes, expand task trees, inspect turns/models, and resume tasks without leaving the terminal.
• Scriptable CLI — Export human-readable text or schema-versioned camelCase JSON, select individual sections, and filter turns by thread.
• Server-friendly — Works in SSH, tmux, and Zellij sessions; Linux release binaries are static musl builds with no host glibc dependency.
• Read-only monitoring — Reads local Codex data and account gauges without reading auth.json or consuming reset credits.
• Low-overhead refreshes — Uses a persistent incremental cache and event-driven TUI updates to avoid repeatedly parsing unchanged rollouts.

Installation

Install a release binary

The shell installer supports macOS and Linux on x8664 and ARM64. It verifies the release archive against SHA256SUMS; the default installation requires no sudo and uses ~/.local/bin.

curl --proto '=https' --tlsv1.2 -fsSLO \
  https://github.com/ghostroller/codex-usage-monit/releases/latest/download/install.sh
sh install.sh

You can inspect install.sh before running it. The installer adds its directory to PATH for common POSIX shells when it can do so safely; otherwise it prints the exact PATH command to run manually.

Useful installer options:

# Install a specific release
sh install.sh --version vX.Y.Z

# Choose the destination
sh install.sh --install-dir "$HOME/bin"

# Leave shell profiles unchanged
sh install.sh --no-modify-path

To upgrade, download the latest installer again and rerun it, then restart any running TUI. The application does not provide a self-update function.