claudex-limits

See how much Codex and Claude allowance you have left, plus your Codex credit balance, without leaving the terminal.

claudex-limits prints a snapshot or a live chart of account quota windows. By default, --live uses the shared limits server that also supplies the embedded display. The first response includes a week of saved readings on updated servers, or four hours on older servers. Local snapshots detect existing Codex and Claude Code logins automatically, without starting a model turn. They show both accounts when both are signed in. Codex readings use blue shades and Claude readings use orange shades, including reset details. Credit balances use cyan with a separate numeric axis on the right.

Demo with five-hour and weekly quotas, credits, reset timers, and banked resets.

Linux and macOS are supported on amd64 and arm64. Windows is unsupported. This is an independent project, unaffiliated with OpenAI or Anthropic.

Quick start

Download a release archive for your platform and follow the installation instructions, or build from source.

After installation, run the server-backed live chart:

claudex-limits --live

It uses the embedded display's HTTPS endpoint and a private service bearer file. See server connection for its path and overrides.

For local account reads, sign in with the Codex CLI or Claude Code, then run:

claudex-limits
claudex-limits --source auto --live

Snapshots discover both providers by default. An explicit --source selects local account discovery for live mode too:

claudex-limits --source codex
claudex-limits --source claude
claudex-limits --source claude --live

Try the chart without an account or network access:

claudex-limits --demo --live

The default overlays five-hour quotas, weekly quotas, and credits on one grid, with a five-hour time axis above and a weekly time axis below. Focus on either scale, or put the scales on two grids:

claudex-limits --live --scale 5h
claudex-limits --live --scale week
claudex-limits --live --layout split

Use Ctrl+C to quit. The command restores the cursor and previous terminal screen. claudex-limits --json prints one machine-readable snapshot.

Install a release

Download the matching archive and SHA256SUMS from Releases. A downloaded binary needs no Go toolchain or Python.

System	Processor	Target
Linux	Intel or AMD 64-bit	linux-amd64
Linux	ARM 64-bit	linux-arm64
macOS	Intel	darwin-amd64
macOS	Apple silicon	darwin-arm64

In the directory containing your downloads, set the version and target to match the archive you chose. For v0.1.0 on Linux amd64:

version=0.1.0
target=linux-amd64
archive="claudex-limits-$version-$target.tar.gz"

Verify the selected archive on Linux:

awk -v archive="$archive" '$2 == archive { print }' SHA256SUMS | sha256sum -c -

Or verify it on macOS:

awk -v archive="$archive" '$2 == archive { print }' SHA256SUMS | shasum -a 256 -c -

Continue only if the check prints OK. On either system, unpack and install:

mkdir -p "claudex-limits-$version-$target"
tar -xzf "$archive" -C "claudex-limits-$version-$target"
mkdir -p "$HOME/.local/bin"
install -m 0755 "claudex-limits-$version-$target/claudex-limits" "$HOME/.local/bin/claudex-limits"
export PATH="$HOME/.local/bin:$PATH"
claudex-limits --version

The export adds the install directory to PATH for the current shell. Add that line to your shell configuration to keep it for future terminals.

Build from source

Install Go 1.26 or newer, Git, and Make. Clone the repository, or use an existing checkout:

git clone https://github.com/unmanbearpig/claudex-limits.git
cd claudex-limits
make build VERSION=dev
mkdir -p "$HOME/.local/bin"
install -m 0755 claudex-limits "$HOME/.local/bin/claudex-limits"
export PATH="$HOME/.local/bin:$PATH"
claudex-limits --demo --live

The project uses only the Go standard library. Go is needed to build the executable, not to run it. A local account read normally also needs the Codex CLI installed and signed in. Claude usage reads can use Claude Code's saved OAuth credentials directly.

Server connection

--live defaults to https://limits.144.217.254.157.sslip.io/v1/usage, the same server used by the embedded display. It refreshes every 30 seconds; the server polls providers every minute. The service bearer is read from $XDG_DATA_HOME/claudex-limits/service-private/device-token.json, or ~/.local/share/claudex-limits/service-private/device-token.json when XDG_DATA_HOME is unset.

The file must be a private regular file with mode 0600, containing only access_token, the server's 43-character base64url bearer. Use the service bearer already provisioned for the display. Provider OAuth credentials are a different format and cannot authenticate to this endpoint.

Override either setting with --service-url and --service-token-file, or CLAUDEX_LIMITS_SERVICE_URL and CLAUDEX_LIMITS_SERVICE_TOKEN_FILE:

claudex-limits --live --service-token-file /private/path/device-token.json
claudex-limits --source server --json

The client verifies HTTPS certificates, refuses redirects, and rereads the bearer file on each refresh. Tokens stay out of command output and history. The server supplies the main primary and secondary quota windows. Additional model buckets, spending, and banked resets are available through local sources. Updated servers also supply Codex credits. The client requests version 5 for a week of credit and quota history and credits used today. It falls back to version 4 negotiation on older servers; versions 1 through 4 remain accepted. The daily estimate sums observed balance decreases in the server's configured calendar timezone and survives restarts and chart pruning. partial means earlier readings or uninterrupted coverage are missing. Additions do not erase previously observed usage; changes between polls can affect the estimate. No endpoint or bearer change is needed.

--source auto --live uses local logins and their saved desktop history. An explicit --auth-file also keeps live mode on a local account source.

Flags

--json                 print one JSON snapshot and exit
--live                 load saved server history and refresh until Ctrl+C
--scale auto|5h|week    both time scales by default, or focus on one
--layout overlay|split one shared grid by default, or two stacked grids
--show-nimbus-quill     include Claude's Nimbus Quill quota bucket
--interval SECONDS     live refresh interval: server 30, local 5, Claude alone 60
--source server|auto|codex|proxy|claude
                       default server with --live, auto for snapshots
--auth-file PATH       use exactly this OAuth file; add --source claude for Claude
--service-url URL      override the HTTPS limits server endpoint
--service-token-file PATH
                       use this private service bearer JSON file
--demo                 use synthetic data, without login or network
--version              print the build version
--help                 print flag help

--interval must be positive and finite, and only works with --live. --scale and --layout also require --live. Their defaults are auto and overlay. --json and --live cannot be combined. --auth-file cannot be combined with --source codex, --source proxy, or --source server. Service flags require the default --live source or an explicit --source server. --demo cannot be combined with an explicit account source or service flags.

Accounts and privacy

With --source auto, including the default snapshot mode, the command discovers Codex and Claude independently. If both logins are present, successful readings remain visible when the other provider fails. Codex discovery uses codex app-server when the Codex CLI is available. If the CLI is missing or reports no ChatGPT login, it checks the native OAuth file and then the proxy OAuth directory. A transient failure from an authenticated app server is reported instead of switching Codex accounts. --source codex never falls back to a file or another provider.

The native file is ${CODEX_HOME}/auth.json when CODEX_HOME is set, or ~/.codex/auth.json. The Codex CLI can also use a platform keychain, which the app server reads for the monitor. An API key is not a ChatGPT OAuth account; use codex login for the app-server source.

The proxy fallback selects the most recently modified active codex-*.json under ~/.config/cliproxyapi/auth. --auth-file selects exactly one file. It accepts native nested tokens.access_token and tokens.account_id fields, or flat proxy access_token and account_id fields.

The file-based source sends authenticated GET requests to the ChatGPT account endpoints at chatgpt.com/backend-api/wham/. It reads credentials without editing or refreshing them. The Codex CLI owns credential refresh for the app-server source. No OAuth credentials are included in JSON output or saved quota history. There is no project telemetry.

Claude discovery reads ${CLAUDE_CONFIG_DIR}/.credentials.json, or ~/.claude/.credentials.json when CLAUDE_CONFIG_DIR is unset. On macOS, the selected Claude Code Keychain item takes precedence over that file. The monitor reads that item with /usr/bin/security, the same reader used by Claude Code. macOS may ask for Keychain access if that reader is not already authorized. Denied access is reported as unavailable, and reads use the request timeout. Automatic discovery uses the local claude auth status command to check for a Keychain login. No browser login flow is opened.

If the default Claude file is absent on Linux, discovery checks the most recently modified active claude-*.json in ~/.config/cliproxyapi/auth. A custom CLAUDE_CONFIG_DIR selects that configuration without falling back to a proxy account. --source claude --auth-file PATH selects exactly one native or flat proxy OAuth file and bypasses the Keychain. --auth-file without a Claude source continues to select a Codex file.

Claude reads use GET https://api.anthropic.com/api/oauth/usage with the saved OAuth access token and anthropic-beta: oauth-2025-04-20. This is an undocumented account endpoint used by quota monitors, so Anthropic may change it. It reports the allowance percentages and reset times available to that login. API keys and inference-only tokens cannot provide Claude subscription quotas.

The monitor reads Claude credentials again on each fetch, so it picks up refreshes made by Claude Code. It never refreshes or rewrites those credentials itself. Expired tokens produce an error until Claude Code refreshes them. Claude usage fetches run once a minute in a combined chart. Claude-only charts default to 60 seconds and accept --interval overrides. HTTP 429 responses pause requests for at least a minute and respect a longer Retry-After value.

Never attach OAuth files, tokens, or unredacted account logs to an issue.

Live chart and history

The chart uses colored Braille characters with two dot columns each. The newest reading is on the right. Overlapping lines alternate colors by character; the two dots in each character share one color. Codex lines use blue shades; Claude lines use yellow/amber shades. The color legend sits below the chart. Five-hour quotas use a five-hour horizontal scale. Weekly quotas and credits use a one-week scale, with dates on the axis. Quotas with other durations use the five-hour scale up to five hours, and the weekly scale above that. Both scales share one grid by default, with five-hour times above it and weekly dates below. Both axes end at the current time on the right. --layout split puts each scale on its own grid. --scale 5h or --scale week shows only that scale. An empty group is omitted from the default view. Credits use cyan and their own right axis in credit units, from zero to the highest balance in the visible history. An all-zero history uses a zero-to-one axis. The current balance and today's usage appear below the chart and quota rows. Older quota readings without credit balances leave gaps in the credit trace. On shorter terminals, extra quota legend rows collapse to keep the chart in view.

The CLI uses the terminal's ANSI palette: blue and bright blue for Codex, yellow and bright yellow for Claude, cyan for credits, and gray for axes and grid lines. The terminal supplies readable shades for its background. Switching with theme bright or theme dark recolors an open chart immediately. When both scales share a grid, five-hour lines use regular provider colors and weekly lines use their bright variants. Their legend markers match. Split grids use the bright provider colors for both time scales. Focused views use regular colors for five-hour quotas and bright colors for weekly quotas. Quota rows show whole percentages, such as Codex 5h · 0% · reset in 2h 33m. JSON keeps the reported precision.

Missed refreshes appear as gaps; the last successful values remain visible and are marked stale. Use a Unicode/ANSI-capable terminal and resize it to adjust the chart. Resizing redraws immediately without fetching another reading. The chart fills the available height after reserving space for the legend and status messages.

Claude's Nimbus Quill bucket is hidden in text output and the live chart by default. Use --show-nimbus-quill to include it. JSON snapshots and saved history retain every reported bucket.

Server charts use the server's observation timestamps and history columns. Primary and secondary labels keep those columns stable when window metadata changes. The legend shows reported durations and reset times. Unknown quotas remain unknown; failed provider polls produce gaps and retain the previous reported values with a stale marker. Successful readings older than three minutes also become stale. A client connection failure retains the chart until the next response supplies current server history. Updated servers retain history indefinitely and supply the last week on every response, including after a CLI restart. Older servers supply four hours; the CLI retains their observations for up to a week during the live session. Server charts use no desktop history files.

Every local snapshot is saved, including normal calls, --json, and live refreshes. Starting a local live chart restores the last week. History lives in:

• Linux: $XDG_CACHE_HOME/claudex-limits/history, or ~/.cache/claudex-limits/history when XDG_CACHE_HOME is unset.
• macOS: ~/Library/Caches/claudex-limits/history.

Recent readings in the previous codex-limits/history cache directory are also loaded until they are older than a week. New readings are saved under claudex-limits/history. To clear all history after upgrading, delete both directories.

Each OAuth file path, Claude configuration, and Codex home has separate history. Combined provider selections have their own history. Changing the account within the same file or configuration keeps that source's history; delete its history directory if you want a fresh chart.

Snapshots are appended to hourly files so concurrent calls do not overwrite earlier readings. Old hourly files are pruned on later calls for that source. Delete the history directory to clear saved readings. Storage failures warn on stderr while fetched limits remain available. --demo neither reads nor writes saved history.

JSON output

claudex-limits --json preserves these fields:

• five_hour_remaining_percent and weekly_remaining_percent are percentages left. Matching *_reset objects contain after_seconds, local at, and Unix timestamp.
• additional_rate_limits contains named five-hour and weekly windows for other buckets.
• windows contains every recognized window, including 15-minute, hourly, and other durations. Items contain name, optional remaining_percent, optional window_seconds, and an optional reset object.
• banked_resets.available is authoritative when present. applicable appears when reported. expirations lists known available credit expirations; expiration_details_partial means those details are incomplete.
• credits contains Codex's reported balance, has_credits, and unlimited. The balance uses credit units, with no currency conversion. Missing values are null; a zero balance and false flags remain explicit. The object is omitted when no credit summary is available. Snapshot text and the live footer show credits separately from percentages and banked resets. JSON and local saved snapshots retain more decimal places; text rounds to two decimals.
• plan_type is descriptive. It does not determine supported quota windows.
• Claude-only responses include provider: "claude" and use the same remaining percentage and window fields. Model-specific and other reported windows are retained, including the newer limits response array.
• When both providers are discovered, provider is "all", and accounts contains each provider's snapshot or error. Combined windows have provider prefixes, such as Claude / 5h. Original top-level five-hour, weekly, plan, additional-limit, credit, and banked-reset fields continue to refer to Codex.
• Claude's optional extra_usage contains is_enabled, reported monthly_limit and used_credits, and optional remaining_percent and currency. Spending amounts preserve the endpoint's units, generally minor currency units. A percentage is shown only for an enabled, positive monthly cap. No monthly reset time is inferred.
• --source server --json uses the same snapshot format. Each account also has state and optional observed_at from the service. A failed account may retain a last successful snapshot alongside its error. Window names use the server's primary and secondary identity, and no extra quota buckets are added. Version 2 servers include the latest Codex credit summary; version 3 also supplies actual credit balances in history. Failed provider polls retain that balance with the same observation timestamp and stale state.

Unknown percentages and durations are omitted. An empty windows list means no quota windows were reported, not 100% remaining or unlimited usage.

Troubleshooting

• limits server token file not found: pass --service-token-file PATH for the bearer provisioned for the display, or use --source auto --live for local account reads.
• limits server rejected the service bearer: replace the private bearer file with the token configured on the server.
• no ChatGPT account is available: run codex login, then retry. You can also pass a known OAuth file with --auth-file PATH.
• ChatGPT rejected the saved OAuth token: make a Codex request so the CLI can refresh its credential, then retry.
• Claude OAuth token has expired: reopen Claude Code to let it refresh the credential, then retry. Use claude auth login if the login was revoked.
• Claude OAuth token lacks user:profile scope: use a Claude Code subscription login. claude setup-token tokens provide inference access without quota access.
• macOS Keychain denied access to Claude OAuth credentials: allow /usr/bin/security to read the Claude Code-credentials item in Keychain Access, then retry. You can also select an existing OAuth file with --source claude --auth-file PATH.
• No quota windows reported: the response was valid but contained no recognized quota values. Check the account and try again later.
• claudex-limits: command not found: check that $HOME/.local/bin is on PATH and that the installed executable is named claudex-limits.
• Redirected --live output uses plain-text frames. NO_COLOR=1 disables color; TERM=dumb also disables the alternate screen.

Development and releases

Run the checks locally:

gofmt -l *.go
make test
make vet
make race

Formatting is clean when gofmt -l prints nothing. Tests use offline fixtures and fake app-server processes. They cover credentials, account responses, quota normalization, chart gaps, history persistence, concurrent writes, CLI validation, and subprocess cleanup. Server tests cover authenticated HTTPS, certificate verification, redirects, bounded responses, private token files, exact document validation, imported history, stale provider values, client outages, and cancellation.

Build the four Linux and macOS archives:

make release VERSION=0.1.0

Outputs go to dist/0.1.0/. Each archive contains an executable named claudex-limits, this README, the quota interface notes, the screenshot, the synthetic preview, and the MIT license. SHA256SUMS lists exactly the four archives for that version. Builds use CGO_ENABLED=0 and have no native library dependency.

Releases are manual. After local checks pass, tag the reviewed commit with the matching version, such as v0.1.0, and attach that version's four archives and SHA256SUMS to its GitHub release. There is no CI or automatic publishing.

Terminal runtime verification has been performed on Linux. Claude Keychain and quota reads have also been tested on macOS with a saved Pro login.

Codex CLI 0.155.1 was checked for app-server startup and logged-out account handling. A live quota read also passed through the OAuth-file fallback. Signed-in app-server responses are covered by offline fixtures.

Claude support is covered by offline fixtures for both usage schemas, automatic discovery, credential rotation, partial provider failures, rate-limit backoff, history, cancellation, and orange chart rendering. An authenticated live Claude quota read passed on Linux, returning five-hour, weekly, and additional provider windows. A macOS read through /usr/bin/security also passed, returning five-hour and weekly quota windows.

To regenerate the synthetic preview, build the binary and run python3 scripts/render-demo.py. Python is only used for this documentation utility.

License

MIT. Copyright 2026 unmanbearpig.

Account interface references

• Codex authentication and credential storage
• Codex app-server account API
• Claude quota interface research