cc-usage_skill

Overview

This skill analyzes local Claude Code logs to produce token usage and API-equivalent cost statistics broken down by date and model. It runs a standalone Python script that scans ~/.claude/projects/, aggregates usage, and returns readable summaries and tables. The output highlights daily subtotals, totals, model cost rankings, and flags unusual spikes.

How this skill works

The skill runs a pure Python 3 analyzer that reads Claude Code log files under the user's home directory and groups tokens by date and model. It converts token counts into API-equivalent costs using configured pricing, computes daily and overall totals, and detects anomalies such as sudden usage spikes. Results are formatted as a Markdown table and can be exported as CSV or a model-only summary.

When to use it

• When you want a quick breakdown of Claude Code token consumption by date and model
• To review recent usage for the last N days (default: 7 days)
• When auditing cost drivers to identify the most expensive models
• Before adjusting usage policies or debugging unexpected billing increases
• When you need CSV output to analyze further in Excel

Best practices

• Run the analyzer from an account that owns the ~/.claude/projects/ logs to ensure full access
• Use the --days option to limit scope for faster results and focused troubleshooting
• Filter by --project with a fuzzy name to isolate specific project usage
• Keep MODEL_SHORT and PRICING dictionaries updated when new models are added
• Check flagged anomalies promptly—large one-day spikes often indicate a runaway job

Example use cases

• Get a 7-day token and cost report to share with your team after a development sprint
• Filter usage to a single project to attribute costs for internal chargebacks
• Export CSV for finance to import into a cost-tracking spreadsheet
• Run a summary to quickly identify which model is driving the highest API-equivalent spend
• Detect an unexpected spike on a specific date and trace it back to recent commits or jobs