home / skills / openclaw / skills / codex-quota

codex-quota skill

safe

This skill reports OpenAI Codex CLI quotas by reading local session logs and can query all accounts for live, synchronized quota data.

npx playbooks add skill openclaw/skills --skill codex-quota

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

1.4 KB

---
name: codex-quota
version: 1.2.2
homepage: https://github.com/odrobnik/codex-quota-skill
description: >
  Check OpenAI Codex CLI rate limit status (daily/weekly quotas) using local
  session logs. Portable Python script.

  Reads ~/.codex/sessions/ for quota data.
  When using --all --yes, it temporarily switches accounts by overwriting
  ~/.codex/auth.json (restored afterwards) to query each account.

  Uses the `codex` CLI for --fresh / --all.
metadata:
  openclaw:
    requires:
      bins: ["python3", "codex"]
---

# Skill: codex-quota

Check OpenAI Codex CLI rate limit status.

## Quick Reference

```bash
# Run the included Python script
./codex-quota.py

# Or if installed to PATH
codex-quota
```

## Options

```bash
codex-quota              # Show current quota (cached from latest session)
codex-quota --fresh      # Ping Codex first for live data
codex-quota --all --yes  # Update all accounts, save to /tmp/codex-quota-all.json
codex-quota --json       # Output as JSON
codex-quota --help       # Show help
```

## Setup

See [SETUP.md](SETUP.md) for prerequisites and setup instructions.

## What It Shows

- **Primary Window** (5 hours) — Short-term rate limit
- **Secondary Window** (7 days) — Weekly rate limit
- Reset times in local timezone with countdown
- Source session file and age

## When to Use

- Before starting heavy Codex work (check weekly quota)
- When Codex seems slow (might be rate-limited)
- Monitoring quota across multiple accounts

Overview

This skill checks OpenAI Codex CLI rate limit status using local session logs and optional live queries. It is a portable Python script that summarizes short-term (5-hour) and weekly (7-day) quotas, reset times, and session sources. The tool can output JSON and temporarily switch accounts to collect quotas across multiple sessions.

How this skill works

The script reads session data from ~/.codex/sessions/ to compute cached quota usage, reset timestamps, and session age. With --fresh it calls the codex CLI to retrieve live quota information; with --all --yes it temporarily overwrites ~/.codex/auth.json to iterate accounts, restoring the original file afterwards. Output includes local timezone reset countdowns, source session file, and an optional JSON export saved to /tmp/codex-quota-all.json.

When to use it

Before starting heavy Codex work to confirm weekly and short-term quotas
If Codex responses are slow or failing and you suspect rate limiting
When managing or monitoring quotas across multiple Codex accounts
To generate a quick JSON snapshot for automated monitoring or reporting

Best practices

Run without flags to view the cached status quickly from session logs
Use --fresh sparingly to avoid extra API calls when you only need recent cached info
When using --all --yes, ensure no concurrent codex CLI operations run to avoid auth conflicts
Backup ~/.codex/auth.json before experimenting; the script restores it but backups reduce risk
Use JSON output for integrations with dashboards or alerting systems

Example use cases

Check current 5-hour and 7-day quota before a large code-generation run
Audit quota usage across team accounts by running --all --yes and exporting JSON
Troubleshoot perceived API slowdowns by confirming whether rate limits were hit recently
Integrate with a cron job to capture daily quota snapshots for historical tracking

FAQ

Is it safe to use --all --yes since it overwrites auth.json?

The script temporarily overwrites ~/.codex/auth.json and restores the original file after querying. Close other codex CLI processes before running and keep a manual backup for extra safety.

Where is the multi-account JSON saved?

When you run with --all --yes the aggregated JSON is saved to /tmp/codex-quota-all.json by default for easy retrieval and further processing.