codex-usage

Unofficial local CLI for inspecting ChatGPT Codex usage/limits from auth files that already exist on your machine.

What it does

codex-usage looks for local Codex/OpenAI auth files, calls the observed ChatGPT Codex usage endpoint, and prints either a human summary or JSON output.

It can:

• inspect the default local account
• inspect all discovered accounts
• filter by account email substring
• emit JSON for automation
• run a simple monitor with optional systemd timer

Requirements

• Linux or macOS
• bash
• python3
• curl
• local Codex/OpenAI auth already present

The tool searches for auth files in:

• ~/.codex/auth.json
• ~/.cli-proxy-api/auths/codex-*.json

Install

git clone https://github.com/mushinskiydev/codex-usage.git
cd codex-usage
./install.sh

Ensure ~/.local/bin is on your PATH.

Example:

export PATH="$HOME/.local/bin:$PATH"

Usage

Basic usage:

codex-usage
codex-usage --all
codex-usage --account user@example.com
codex-usage --json
codex-usage --auth-file ~/.codex/auth.json

Show help:

codex-usage --help

Output notes

• Human output shows an Auth source label, not the full local file path.
• --json output includes sanitized auth source labels and metadata returned by the endpoint.
• Non-200 responses are surfaced as-is so you can distinguish auth issues from usage-limit issues.

Monitoring

Run the monitor manually:

codex-usage-monitor

Default monitor log directory:

$HOME/.local/state/codex-usage/logs

Artifacts written by the monitor:

• latest.json
• summary-YYYYmmdd-HHMMSS.txt
• issues-latest.txt

Enable the user timer after installation:

systemctl --user enable --now codex-usage-monitor.timer
systemctl --user status codex-usage-monitor.timer --no-pager

Default schedule:

• first run about 3 minutes after enabling or login/boot
• then every 15 minutes

Privacy and security

• The tool reads existing local auth files; it does not create or mint tokens.
• Access tokens are used only in memory for the API request.
• Do not publish raw JSON output, logs, or issue snapshots if they contain account identifiers or usage state you consider sensitive.
• Keep your auth files private.

Limitations

• The endpoint used here is unofficial/observed behavior and may change without notice.
• Some local auth files may return 401 even when the file exists; that usually means the local token is expired or not accepted by the endpoint.
• This tool is not affiliated with OpenAI.

Documentation

• docs/api-notes.md
• docs/alerts.md

License

MIT