# Codex Usage

> Check OpenAI Codex usage and banked reset credits in OpenClaw / HermesAgent-style environments that store OpenAI Codex auth locally, with optional direct token input.

- Skill: `leonidlouis/codex-usage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add leonidlouis/codex-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leonidlouis/codex-usage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: leonidlouis (https://skillmd.com/u/leonidlouis)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/leonidlouis/codex-usage

---


# Codex usage

Use this when the user asks things like:
- "what's my codex usage"
- "check codex quota"
- "how much codex do I have left"
- "do I have codex left"
- "how many Codex resets do I have"
- "use/redeem a Codex reset"

## Goal

Return a fast, glanceable summary of OpenAI Codex usage.

This skill is primarily intended for OpenClaw / HermesAgent-style environments that already have OpenAI Codex authentication available locally. It can also be used in other environments by passing a bearer token explicitly.

Default to a concise multi-line summary. Only use the one-line terse variant when the user explicitly asks for terse or one-line output.

## Included helper script

This skill ships with a reusable helper script:

```bash
scripts/codex_usage.py
```

The script:
- accepts a direct access token or a local auth file
- extracts Codex access tokens from standalone Codex CLI auth, Hermes/OpenClaw provider auth, or Hermes credential-pool auth
- sends `ChatGPT-Account-Id` automatically when the auth file contains an account id
- calls `https://chatgpt.com/backend-api/wham/usage`
- includes banked reset-credit count when the endpoint returns `rate_limit_reset_credits.available_count`
- can redeem one banked reset credit via `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume`
- prints either a human summary, terse summary, normalized JSON, or raw JSON

## Prerequisite

You need a valid OpenAI Codex bearer token.

In OpenClaw / HermesAgent-style setups, that token is often already available via local auth storage. In other environments, provide the token directly:

```bash
export OPENAI_CODEX_ACCESS_TOKEN="your_token_here"
python3 scripts/codex_usage.py
```

If your environment already stores Codex auth in a local file, you can point the script at that file instead.

## Auth discovery

The script resolves credentials in this priority order:
1. `--access-token ...`
2. `$OPENAI_CODEX_ACCESS_TOKEN`
3. `--auth-path /path/to/auth.json`
4. `$CODEX_AUTH_PATH`
5. auto-discovered auth files in common local locations

The intended default is OpenClaw / HermesAgent-style local auth. Token-first usage remains fully supported for other agents or standalone shell workflows.

## Preferred commands

Default when local auth is already present, or when `OPENAI_CODEX_ACCESS_TOKEN` is already set:

```bash
python3 scripts/codex_usage.py
```

One-line terse output:

```bash
python3 scripts/codex_usage.py --terse
```

Normalized JSON:

```bash
python3 scripts/codex_usage.py --json
```

Raw endpoint JSON:

```bash
python3 scripts/codex_usage.py --raw
```

Show account email explicitly:

```bash
python3 scripts/codex_usage.py --show-email
```

Use a specific timezone label supported by Python `zoneinfo`:

```bash
python3 scripts/codex_usage.py --tz Asia/Bangkok
```

Use a direct token explicitly:

```bash
python3 scripts/codex_usage.py --access-token "$OPENAI_CODEX_ACCESS_TOKEN"
```

When using a direct token for an account that requires account scoping, include the account id:

```bash
python3 scripts/codex_usage.py --access-token "$OPENAI_CODEX_ACCESS_TOKEN" --account-id "$OPENAI_CODEX_ACCOUNT_ID"
```

Use a custom auth file:

```bash
python3 scripts/codex_usage.py --auth-path /path/to/auth.json
```

Redeem one banked reset credit:

```bash
python3 scripts/codex_usage.py --consume-reset --confirm-consume-reset
```

`--confirm-consume-reset` is required because this is a live account-side effect. Without it, the script refuses to make the consume request.

For retry-safe automation, provide a stable idempotency key. Reusing the same key should return `already_redeemed` rather than consume another reset:

```bash
python3 scripts/codex_usage.py --consume-reset --confirm-consume-reset --idempotency-key "$(uuidgen)"
```

Only run `--consume-reset` after the user explicitly asks to spend a reset credit. It is a real account-side effect.

## Expected terse format

```text
Codex: 95% 5h · 89% week · resets 00:22 / Fri 17 Apr, 17:10 · 3 banked resets
```

## Response style

- Prefer a concise multi-line summary by default
- Use the terse one-line summary only when the user explicitly asks
- Do not include ASCII bars unless requested
- Do not include credits or internal fields unless requested
- Avoid showing account email unless the user asked for it

## Verification

Before replying to a usage-check request, make sure the usage command actually ran successfully and returned live values. For code changes to this skill, prefer offline tests/mocks for reset redemption; do not exercise `--consume-reset --confirm-consume-reset` against a real account unless the user explicitly asks to spend a reset credit.

## Notes

- This skill expects either a valid Codex access token or an auth file containing standalone `tokens.access_token`, `providers.openai-codex.tokens.access_token`, or a `credential_pool.openai-codex` token entry
- If auto-discovery fails, pass `--access-token` or `--auth-path` explicitly
- The reset count is read from `rate_limit_reset_credits.available_count`
- Reset redemption posts `{"redeem_request_id": "..."}` to `/wham/rate-limit-reset-credits/consume`; known response codes are `reset`, `nothing_to_reset`, `no_credit`, and `already_redeemed`
- If the endpoint schema changes, update the helper script first, then refresh the skill instructions