Metadata-Version: 2.4
Name: codex-quota-monitor
Version: 0.2.0
Summary: CLIProxyAPI-backed Codex OAuth quota and usage dashboard with routing scores, NixOS module, and Prometheus metrics
License-Expression: MIT
Project-URL: Homepage, https://xsyxnx.github.io/codex-quota-monitor/
Project-URL: Repository, https://github.com/xsyxnx/codex-quota-monitor
Project-URL: Documentation, https://github.com/xsyxnx/codex-quota-monitor/blob/main/README.en.md
Project-URL: Issues, https://github.com/xsyxnx/codex-quota-monitor/issues
Project-URL: Changelog, https://github.com/xsyxnx/codex-quota-monitor/blob/main/CHANGELOG.md
Keywords: agent-tools,cli-proxy-api,codex,codex-cli,dashboard,monitoring,nix,nixos,oauth,prometheus,quota,self-hosted
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Codex Quota Monitor

[简体中文](README.md)

[![CI](https://github.com/xsyxnx/codex-quota-monitor/actions/workflows/ci.yml/badge.svg)](https://github.com/xsyxnx/codex-quota-monitor/actions/workflows/ci.yml)
[![Python 3.11-3.14](https://img.shields.io/badge/python-3.11--3.14-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## What This Is

A small self-hosted dashboard for people who run Codex OAuth accounts behind [`CLIProxyAPI`](https://github.com/router-for-me/CLIProxyAPI).

Its main job is simple: turn the pool's 5h and weekly quota into Plus-equivalent remaining capacity, so you know how much work the pool can still take.
It also shows which accounts should keep working, when exhausted accounts come back, and whether the pool or the monitor itself needs attention.

Community and contact:

- Matrix space: <https://matrix.to/#/#codex-quota-monitor:matrix.h0pper.xyz>
- Email: <xiashangying2023@outlook.com>

`Usage` / stats views already cover request and token trends from local SQLite history, reducing the day-to-day need to open CPA usage / statistics pages; CPA remains the upstream gateway and is not installed or managed by this project.

If you just want to see the UI, run `cqm --demo` after installation, then open <http://127.0.0.1:4516/>. Demo mode uses built-in sample data and does not need CPA, management keys, or auth files.

![Codex Quota Monitor dashboard](https://github.com/xsyxnx/codex-quota-monitor/releases/download/readme-assets/cqm-screenshot.png)

## Quick Start

You need an existing `CLIProxyAPI` management endpoint. The common local setup is:

- CPA management: `http://127.0.0.1:8317`
- CPA health: `http://127.0.0.1:8317/healthz`
- Dashboard: `http://127.0.0.1:4515`
- A key file containing the same plaintext value as CPA `remote-management.secret-key`

If you want Codex, Claude, or another coding agent to handle installation, smoke tests, or service wiring, start by handing it [Deploy with an agent](docs/deploy-with-agent.md). That guide lists the facts to prepare, safety boundaries, and acceptance checks.

Pick one way to install or run it:

<details open>
<summary>Run with uv / pipx</summary>

Install `uv` first if it is not already available:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

After `v0.2.0` is published, install from PyPI first:

```bash
uv tool install codex-quota-monitor==0.2.0
```

If you prefer `pipx`, install the same version:

```bash
pipx install codex-quota-monitor==0.2.0
```

To preview the source before the tag is published, use `uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'`.

Point it at your CPA:

```bash
cqm \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files
```

Then open <http://127.0.0.1:4515/>.

Before turning it into a service, run:

```bash
cqm print-config
cqm doctor
```

</details>

<details>
<summary>Run with Nix</summary>

```bash
nix run github:xsyxnx/codex-quota-monitor#cqm -- \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files
```

More NixOS module notes are in [docs/nixos-module.md](docs/nixos-module.md).

</details>

<details>
<summary>Run with Docker</summary>

```bash
docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp \
  -p 127.0.0.1:4515:4515 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_BASE_URL=http://host.docker.internal:8317 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_KEY_FILE=/management-key \
  -e CODEX_QUOTA_MONITOR_GATEWAY_HEALTH_URL=http://host.docker.internal:8317/healthz \
  -v codex-quota-monitor-data:/data \
  -v /path/to/management-key:/management-key:ro \
  -v /path/to/auth-files:/auth-files:ro \
  -e CODEX_QUOTA_MONITOR_AUTH_DIR=/auth-files \
  ghcr.io/xsyxnx/codex-quota-monitor:0.2.0
```

To preview the source before the release image exists, build one locally with `docker build -t codex-quota-monitor:local .`.

</details>

<details>
<summary>Use the NixOS module</summary>

```nix
{
  services.codexQuotaMonitor = {
    enable = true;
    managementBaseUrl = "http://127.0.0.1:8317";
    managementKeyFile = "/path/to/management-key";
    gatewayHealthUrl = "http://127.0.0.1:8317/healthz";
    authDir = "/path/to/auth-files";
  };
}
```

The module keeps the service on `127.0.0.1` and keeps the firewall closed unless you explicitly open it. See [docs/nixos-module.md](docs/nixos-module.md).

</details>

For the full install guide, including service files and config files, see [docs/install.md](docs/install.md) and [docs/quick-start.md](docs/quick-start.md).

## Features You May Care About

- Equivalent remaining quota: 5h and weekly windows are shown as Plus-equivalent capacity; Pro is weighted as 20x Plus so you do not have to do pool math by hand.
- Account recommendations: each account gets a `routingScore` for humans and wrappers to rank directly.
- Machine-readable recommendation API: `/api/v1/recommendations` can feed an agent-wrapper without scraping the page.
- Stable API: status, stats, diagnostics, and alerts all use versioned `/api/v1/*` JSON endpoints.
- Stats workbench: `/api/v1/stats/series` exposes SQLite-backed request and token series with JSON and CSV exports.
- ETA estimates: with SQLite history enabled, estimated exhaustion times for the 5h and weekly pools at the current burn rate.
- Demo mode: `--demo` uses built-in sample data, with no CPA, key, or auth files required.
- Grafana: Prometheus `/metrics` is available for dashboards and alerts.
- Security self-audit: dedicated docs cover data flow, secret exposure, and preflight checks.
- Reverse proxy deployments: loopback by default, suitable for tunnels or a dedicated-hostname reverse proxy.
- Redacted display: the UI can mask email addresses and token-like strings for screenshots or remote debugging.
- Import / export: SQLite history keeps trend data and can be backed up, moved, and restored.
- Light / Dark: the dashboard has both modes, so it does not glare next to a dark terminal.
- Custom fonts: set UI and monospace fonts to make Chinese text, numbers, and tokens easier to read.
- Mobile / Kindle: narrow screens still show the core status.
- Logs: foreground-friendly by default, with structured logs for service managers or collectors.
- Nix: flake app/package and a reusable NixOS module are included.
- Agent entry point: docs, APIs, and recommendation groups are ready for agent-driven installation, deployment, and status reads.
- tldr / doctor: `cqm tldr` gives the short version; `cqm doctor` checks the setup before production use or during troubleshooting.

Useful docs:

- [API and metrics](docs/api.md)
- [Security self-audit](docs/security-audit.md)
- [Benchmark guide](docs/benchmark.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Deploy with an agent](docs/deploy-with-agent.md)

## Feedback And Contributions

- GitHub Issues: <https://github.com/xsyxnx/codex-quota-monitor/issues>
- Matrix space: <https://matrix.to/#/#codex-quota-monitor:matrix.h0pper.xyz>
- Email: <xiashangying2023@outlook.com>

Bug reports are most useful when they include the monitor version, how you installed it, whether it talks to raw CPA or a local proxy, and redacted output from `cqm doctor`.

Small docs fixes, deployment notes, and bug fixes are welcome.

## Rough Edges And Roadmap

This is still a focused `0.x` operator tool.

Known limits:

- It does not install or manage `CLIProxyAPI`.
- It does not provide login, RBAC, multi-tenant isolation, or hosted analytics.
- It is not a generic quota tracker for every AI product.
- The browser UI expects to live at the root of its hostname; path-prefix reverse proxy deployments are not supported yet.
- `0.x` API responses may grow new fields. Clients should ignore fields they do not understand.

Next steps:

- More copyable deployment examples.
- More real-world dashboard screenshots and capacity explanations.
- Continued Prometheus alert rule and incident response examples.
- Shorter docs where the current pages are still too dense.
