codex-usage-shadow

name

codex-usage-shadow

description

Estimate Codex token usage, credit burn, and pacing from local `~/.codex` logs when the official usage dashboard is unavailable or incomplete. Use when Codex needs to answer questions like "how much Codex budget have I used?", "am I on pace to exceed $50/month?", "which tasks burned the most tokens?", or "help me ration Codex usage through the week" for a local Codex desktop or CLI installation without admin access.

Codex Usage Shadow

Use this skill to build a local-only shadow meter from Codex's own session files and SQLite state.

Quick Start

Run the bundled script:

python3 scripts/codex_usage_shadow.py --days 7 --monthly-budget-usd 50

For other budgets or windows:

python3 scripts/codex_usage_shadow.py --days 30 --monthly-budget-usd 200 --top 10
python3 scripts/codex_usage_shadow.py --codex-home "${CODEX_HOME:-$HOME/.codex}" --monthly-budget-usd 50

Workflow

1. Assume the user's Codex data lives in ${CODEX_HOME:-~/.codex} unless they say otherwise.
2. Run scripts/codex_usage_shadow.py with the user's monthly budget.
3. Summarize:
   • last-N-days spend
   • month-to-date spend
   • projected month-end spend
   • remaining budget
   • safe weekly pace
   • highest-cost task families
4. If the user asks whether the estimate is trustworthy, read references/assumptions.md and explain the caveats directly.

Interpretation

• Treat Estimated spend as a shadow estimate, not billing truth.
• Treat Projected month-end as the pacing signal.
• Treat Safe weekly pace as the practical rationing number for consultants who need to avoid blowing through a monthly cap.
• If one task dominates the top-cost list, recommend narrowing scope, starting fresh threads sooner, and avoiding parallel sub-agents unless necessary.

What The Script Already Handles

• Reads state_5.sqlite and session jsonl logs.
• Uses detailed token snapshots when session files exist.
• Falls back to threads.tokens_used when they do not.
• Rolls child agents into the parent task family so parallel sub-agents are not double-counted.

Resources

• scripts/codex_usage_shadow.py - local analyzer
• references/assumptions.md - pricing assumptions and known limitations