Problem
Claude Code's /status command shows a basic usage summary, but it doesn't translate token consumption into API-equivalent dollar costs. If you're on a Max plan or Pro subscription, you have no visibility into how much compute you're actually burning. This matters for understanding whether your workflows are cost-efficient, for budgeting if you plan to move to API billing, and for identifying sessions that consume disproportionate resources. Claude Code also purges session log files older than 30 days, so historical usage data is lost unless you back it up.
Solution
Install and run ccusage:
# Run directly with npx (no install needed)
npx ccusage@latest
# For Codex usage tracking
npx @ccusage/codex@latest
ccusage parses the local .jsonl session files that Claude Code stores in ~/.claude/projects/ and calculates API-equivalent costs based on current Anthropic pricing.
Sample output:
Project Input Tokens Output Tokens Cache Read Cache Write Cost
my-app/feature-auth 245,891 34,567 892,345 12,456 $4.23
my-app/refactor-db 189,234 28,901 456,789 8,901 $3.12
personal/scripts 45,678 12,345 123,456 3,456 $0.89
───────────────────────────────────────────────────────────────────────────────────────────────
Total 480,803 75,813 1,472,590 24,813 $8.24
Preserve historical data beyond 30 days:
# Back up session logs before Claude Code purges them
# Run this daily via cron
rsync -av ~/.claude/projects/ ~/claude-code-logs-backup/
# Crontab entry (runs at midnight daily)
# 0 0 * * * rsync -av ~/.claude/projects/ ~/claude-code-logs-backup/
Quick cost check alias:
# Add to your shell profile (~/.zshrc or ~/.bashrc)
alias cc-cost='npx ccusage@latest'
alias cc-cost-codex='npx @ccusage/codex@latest'
Why It Works
Claude Code writes detailed session logs as .jsonl files in ~/.claude/projects/, with one file per conversation. Each log entry includes the model used, input/output token counts, and cache hit/miss data. ccusage reads these files, applies the current Anthropic API pricing tiers (accounting for prompt caching discounts), and aggregates the results by project. This gives you the same cost visibility you'd have if you were calling the API directly, even though you're on a flat-rate subscription plan.
Context
- More information at ccusage.com
- Real-world reports from Max plan users show $1,800-2,200/month in API-equivalent costs, well above the subscription price
- Claude Code purges
.jsonlsession files after 30 days, so the rsync backup is essential for tracking spending trends over time - Token costs include prompt caching -- cached tokens are significantly cheaper than uncached, so workflows that reuse context (like CLAUDE.md files) show lower per-session costs
- ccusage is read-only and runs locally; it does not send any data externally
- Useful for teams evaluating whether to stay on Max plans vs. moving to direct API access