Codex Usage Limits Skill

Codex skill for reading the current Codex usage/rate-limit percentages from local logs, without relying on screenshots.

It reports:

• 5-hour remaining percentage and renewal time
• weekly remaining percentage and renewal time
• used percentage for both windows
• source logs_2.sqlite database and capture timestamp

Requirements

• Codex installed and used at least once, so local Codex logs exist.
• Python 3 with the standard-library sqlite3 module.

No third-party packages are required. No OpenAI API key is required.

Install

Copy the skill folder into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R codex-usage-limits ~/.codex/skills/

On Windows PowerShell:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills"
Copy-Item -Recurse -Force ".\codex-usage-limits" "$env:USERPROFILE\.codex\skills\"

Run Directly

Linux/macOS:

sh ~/.codex/skills/codex-usage-limits/scripts/codex_usage_limits.sh

Windows PowerShell:

& "$env:USERPROFILE\.codex\skills\codex-usage-limits\scripts\codex_usage_limits.ps1"

JSON output:

python3 ~/.codex/skills/codex-usage-limits/scripts/codex_usage_limits.py --json

Exact key/value percentage output:

python3 ~/.codex/skills/codex-usage-limits/scripts/codex_usage_limits.py --percentages

Example:

5h_remaining_percent=70
5h_used_percent=30
weekly_remaining_percent=80
weekly_used_percent=20

Fail when the latest local rate-limit event is stale:

python3 ~/.codex/skills/codex-usage-limits/scripts/codex_usage_limits.py --percentages --fail-if-stale-seconds 300

Why This Skill

This skill is intentionally local and narrow:

• It does not read auth.json.
• It does not read credentials or tokens.
• It does not call private OpenAI/ChatGPT usage endpoints.
• It does not require an API key.
• It reads only local Codex log events from logs_2.sqlite.
• It works as a Codex skill and as a direct script.

Similar public tools often call private usage endpoints, inspect auth material, parse session files, or provide a broader multi-provider dashboard. This project focuses only on reproducing the Codex "usage remaining" percentages from local codex.rate_limits events.

How It Works

Codex emits local websocket log events named codex.rate_limits. The skill reads the newest event from logs_2.sqlite, then converts stored used_percent values into the UI-style remaining percentage:

remaining_percent = 100 - used_percent

The 5-hour window is rate_limits.primary; the weekly window is rate_limits.secondary.

The API currently exposes percentage values as integer used_percent fields. The script returns those exact API integers and computes the UI remaining value as 100 - used_percent. It also reports event_age_seconds so callers can reject stale local events.

If the API starts emitting decimal percentages, the script preserves them instead of truncating. The --percentages mode prints the exact string value, and JSON output includes *_percent_exact fields alongside numeric compatibility fields.

Platform Support

• Windows: supported via Python or scripts/codex_usage_limits.ps1.
• Linux/macOS: supported via Python or scripts/codex_usage_limits.sh.
• Codex App and Codex terminal/CLI are supported when they write local logs under the selected Codex home.

If Codex uses a non-default home directory:

python3 codex-usage-limits/scripts/codex_usage_limits.py --codex-home /path/to/.codex

Or read a database directly:

python3 codex-usage-limits/scripts/codex_usage_limits.py --db /path/to/logs_2.sqlite

Privacy

Do not publish your .codex directory, SQLite logs, auth files, credentials, screenshots, or local output containing private data. This repository contains only the skill code and documentation.