Codex Usage

Track Codex rate-limit balances and reset times across multiple accounts, then see which account to use next.

• Dashboard: https://codexusage.vercel.app
• npm package: codex-usage-dashboard
• Detailed operations guide: pairing, reset tracking, and releases

What it does

• Collects the rate-limit windows reported by the local Codex CLI.
• Displays the real duration of each available window, including weekly-only accounts.
• Plans account order from usable balance and upcoming reset times.
• Projects which reset will make an exhausted account usable again.
• Tracks historical weekly capacity across linked accounts.

Connect a machine

Pair with an existing dashboard account

1. Open https://codexusage.vercel.app and sign in.

2. Select Create pairing command.

3. Run the generated command before its token expires:

   npx codex-usage-dashboard@latest pair "https://codexusage.vercel.app/api/pair/complete?token=..."

4. Keep the dashboard updated when needed:

   npx codex-usage-dashboard@latest sync --watch

The CLI stores the paired-device configuration in ~/.codex/codex-usage-sync.json by default.

Start without a website account

npx codex-usage-dashboard@latest connect --site "https://codexusage.vercel.app"

Weekly-only Codex limits

Do not assume the first window is always 5-hour and the second window is always Weekly. Codex can return one primary window with a duration of 10,080 minutes and no secondary window. That is one Weekly limit, not a 5-hour limit plus a missing Weekly limit.

The dashboard identifies windows by windowDurationMins and ignores absent windows. A null or N/A secondary window must never become a fake 100% balance.

Pairing troubleshooting

Check the public version first:

npm view codex-usage-dashboard@latest version --prefer-online

Version 0.1.6 and newer skip a broken Codex shim injected by an npx environment and probe installed Codex executables for app-server support. Version 0.1.8 and newer also self-repair when every installed and bundled candidate is broken: the CLI installs a fresh private Codex runtime under ~/.codex/codex-usage-runtime using an isolated npm cache, verifies app-server, and reuses that runtime on later runs.

Set CODEX_USAGE_RUNTIME_DIR to move the private runtime. Set CODEX_USAGE_DISABLE_AUTO_REPAIR=1 to opt out of automatic network repair.

If pairing still reports a native Codex ENOENT, test through a clean npm cache:

npm_config_cache="$(mktemp -d)" npx --yes codex-usage-dashboard@latest pair "PAIRING_URL"

If automatic repair also fails, confirm the installed Codex CLI works:

command -v codex
codex --version
codex app-server --help

Generate a fresh pairing command if the old token expired.

Development

npm install
npm test
npm run typecheck
npm run lint
npm run build

Release

On the release branch, bump the version without creating a local tag and run the checks:

npm version patch --no-git-tag-version
npm test
npm run typecheck
npm run lint
npm run build
npm run release:check

Commit and merge that version bump. From the merged checkout, publish in an interactive terminal:

npm publish

If npm prints an authentication URL, leave npm publish running, open that URL, and approve with the configured security key or Touch ID. Authentication against a canceled publish process does not publish the package.

Verify the registry without a stale local response:

npm view codex-usage-dashboard@latest version --prefer-online

Incident documentation

• Pairing, weekly-only reset tracking, and npm release runbook
• OAuth and invite host regression