Use Cases And Coverage

简体中文

Use this page when you need to decide whether codex-quota-monitor covers a real workflow, or when you are planning product, documentation, and test coverage for a CLIProxyAPI-backed Codex OAuth pool.

The project is intentionally focused on Codex OAuth pool operations. It is not a generic multi-provider desktop usage tracker, a SaaS analytics collector, or a CLIProxyAPI installer.

Coverage Matrix

User	Job to do	Needed data	Product surface	Acceptance check
Pool operator	Know whether the Codex pool can take more work right now.	CPA auth state, CPA usage, optional direct quota windows.	Pool, Resets, Stats, Alerts, `/api/v1/status`.	The dashboard shows known 5h and weekly capacity, unhealthy accounts, cooldowns, reset times, and live stats without hiding `Unknown` data.
Agent wrapper author	Pick an account or avoid sending work to a bad account.	Account health, quota state, cooldowns, reclaim hints.	`/api/v1/recommendations`, `/api/v1/alerts`, Prometheus `/metrics`.	`routingScore` ranks accounts and explains the routing choice without exposing auth secrets.
Self-hosted deployer	Install the monitor without widening network exposure by accident.	Management URL, management key file, health URL, optional auth directory.	Quick start, install guide, NixOS module, Docker image, `init`, `doctor`.	A local smoke test passes on `127.0.0.1`; LAN exposure requires an explicit reverse proxy/firewall choice.
Incident responder	Find out why quota, usage, or health is missing or wrong.	Diagnostics for CPA, gateway health, direct quota sampling, SQLite history, benchmark import.	Diagnostics, Alerts, troubleshooting guide, `/api/v1/diagnostics`.	The failing source is named clearly, support data can be shared without auth secret contents, and `Unknown` is not treated as `n/a`.
Capacity planner	Estimate burn rate, reset timing, pool exhaustion risk, and usage shape.	SQLite history, recent usage details, quota windows, optional benchmark summary.	Trends, Stats, Audit, Resets, benchmark guide, native history backup.	Recent trends show burn rate and ETA when enough history exists, Stats separates live/cumulative/history data, and benchmark-derived assumptions are visible instead of implicit.
Read-only viewer	Check current pool state from a browser on desktop, phone, or small screen.	Browser snapshot from the monitor service.	Dashboard tabs and responsive layout.	The page renders without requiring write access, credential access, or operator shell access.
Agent-assisted deployer	Hand the integration task to a coding agent with bounded authority.	Target host, flake input, service options, validation commands.	Deploy-with-agent guide, NixOS module docs, agent discovery page.	The agent can wire the module and run static checks, while live system activation remains an explicit operator step.

Core Scenarios

First install

Start from the quick start or install guide.
Use codex-quota-monitor init --mode user when a rootless systemd starter is useful.
Provide a reachable CPA management endpoint and management key file.
Add an auth directory only if direct Codex quota sampling is desired.
Keep the default listener on 127.0.0.1 unless LAN access is an explicit requirement.

Success means /healthz, /api/v1/status, /api/v1/diagnostics, /api/v1/recommendations, /api/v1/alerts, and /metrics respond locally, and the dashboard opens in a browser.

Daily pool check

Read the Pool, Resets, Stats, and Alerts tabs before starting heavy work.
Treat Team, Prolite, and Pro capacity according to the dashboard’s Plus-unit aggregation rules.
Treat CPA cooldown, direct quota exhaustion, and missing quota data as separate states.

Success means an operator can tell whether the pool is usable now, which quota window blocks recovery, and which accounts need attention.

Agent routing

Use /api/v1/recommendations as the wrapper-facing interface.
Sort /api/v1/recommendations.items by routingScore, and skip accounts where routingEligible is false.
Use reclaimEligible and reclaimWindow as hints for soon-resetting healthy 5h quota, not as a replacement for the recommendation groups.

Success means a wrapper can make a routing decision without scraping HTML or reading auth files.

Unknown quota investigation

Use Diagnostics first to identify whether CPA, gateway health, auth file access, direct quota sampling, SQLite, or benchmark import is failing.
Keep Unknown for data that may appear later.
Use n/a only for states that are truly inapplicable.

Success means support output can explain the missing source without leaking credential material.

Trends and benchmark calibration

Enable a writable SQLite state database when burn rate, ETA, Audit, the Stats time-series workbench, or native history backup matter.
Import a benchmark summary.json when the operator has measured plan-specific capacity or fast-versus-baseline behavior.
Use export-history / import-history for native monitor history migration; the JSON backup preserves derived account and stats history, not auth secrets.
Keep benchmark result directories private because they may contain sensitive selectors, token counts, or copied auth files if retained.

Success means the dashboard makes capacity assumptions visible and avoids silently mixing reset-crossing or incomplete benchmark samples into averages.

Explicit Non-goals

Monitoring Claude, Gemini, Cursor, Copilot, and Codex in one generic desktop quota tracker.
Installing, configuring, or replacing CLIProxyAPI.
Creating accounts, harvesting credentials, bypassing provider policy, or hiding provider-side limits.
Providing SaaS-hosted analytics or public cloud collection.
Providing browser extensions, menu bar apps, mobile apps, or VS Code extensions.
Replacing operator-controlled deployment and live activation workflows.

How To Use This Matrix

Product planning: add a row only when a real user, job, data source, surface, and acceptance check are all clear.
Documentation: keep task instructions in the quick start, install, troubleshooting, benchmark, and deployment docs; keep this page as the scenario index.
Testing: turn acceptance checks into unit, handler, static docs, or manual smoke tests depending on the surface affected.
Agent selection: use the shorter Agent discovery page for quick fit checks, then use this page when the task needs scenario-level coverage.