Limit
Run the script that ships next to this file (python instead of python3 on Windows;
adjust the path if you installed the skill somewhere else):
bashpython3 ~/.claude/skills/limit/scripts/limit.py --color always
Show the output verbatim before summarising it — do not paraphrase the numbers.
A window whose warnings include stale, window expired, or live fetch failed
is unknown, not empty. Don't treat its percentage as current.
Acting on it
Each window has its own wall, and the reset time matters as much as the percentage:
| Reading | Do |
|---|---|
| Both windows of a pool clear | Use the pool normally. Don't hedge or narrate the number. |
| A window within ~5 points of full | Narrow the work: fewer parallel jobs, cheapest model that can carry it, sequential. Say the number once. |
| 5-hour window at the wall and resets within ~30 min | Wait for the reset. Don't hand off to the other pool or start a long run that will be cut in half. |
| Weekly window at the wall | It won't come back for days: hand the work to the other pool if both of its windows are clear, otherwise keep it in the main loop or queue it. |
| Both pools at a wall, or a window unknown | Delegate nothing. Report both numbers and ask. |
The fullest valid window in each pool is binding — a 12% 5-hour window next to an exhausted weekly window means the pool is exhausted. Keep a few percent in reserve for whatever must run at the end of a session (handoff notes, summaries): a job that dies mid-flight costs more than one that never started.
Sources, in order
- Claude: live
https://api.anthropic.com/api/oauth/usagecall using the token in~/.claude/.credentials.json→ optional--claude-observation PATHfile →~/.claude.jsoncache (cachedUsageUtilization, only refreshed by an interactive/usagecall, can be hours stale). - Codex: CodexBar's local cache:
%APPDATA%/CodexBar/codex-accounts/snapshots.jsonon Windows,~/Library/Application Support/CodexBar/codex-account-snapshots.jsonon macOS (Swift Codable format), or$XDG_CONFIG_HOME/CodexBar/codex-accounts/snapshots.jsonon Linux (~/.configby default, when a compatible writer exists). Then the newest dated corerate_limitsevent in up to 40 recent files under$CODEX_HOME/sessions/**/*.jsonl(~/.codexby default). File modification time never stands in for measurement time. A malformed trailing line does not erase the last valid event. A newer empty measurement remains unknown.
CodexBar cache files are not live fetches. Older than 45 minutes, future-dated,
undated, or expired measurements are unknown. limitReached sentinels contain
no trustworthy per-window percentages and are shown as unknown. Multiple
accounts require --codex-account ID using the ID from the local snapshot file;
records from different accounts are never combined. An unavailable selected
account does not fall through to unscoped session data. Session fallback cannot
prove that an event belongs to the currently signed-in account.
The Claude live path supports the credentials JSON file, not macOS Keychain-only credentials. In that case it falls back to observations/cache with a warning. The dashboard does not log tokens or follow authenticated HTTP redirects.
--claude-observation file schema
Wire your own statusline/hook to write a small JSON snapshot more often than the
/usage cache refreshes, then pass its path with --claude-observation:
json{"epoch": 1758100000, "five": 18.0, "seven": 92.0, "five_reset": 1758113500, "seven_reset": 1758350000}
epoch (unix seconds), five/seven (0–100, the 5-hour/7-day window percentages)
are required; five_reset/seven_reset (unix seconds) are optional. Older than 45
minutes is ignored. All-zero values are treated as unreadable, not an empty pool
— an upstream HTTP 429 can write 0 where it means "could not measure".
Limits
- No per-model weekly windows for Claude (e.g. a Max-plan Opus-specific window) — whatever extra windows the live endpoint returns are shown, but nothing is synthesized if it doesn't return them.
- CodexBar is optional; without it the script falls back to session rollout files,
which are only written while
codexis running and can be stale for days. - These are subscription usage windows (percent of a rolling quota), not token counts.
