ccusage and codeburn: Track your Claude Code usage and costs
Using Claude Code every day but have no idea how many tokens you’re burning? Not sure which sessions you ran today, or which model is eating the most? ccusage and codeburn are two small tools that solve exactly that - running locally, no API key needed, set up in minutes.
When you first start using Claude Code, usage tracking is the last thing on your mind. But after a few weeks of real work - long debugging sessions, code with large contexts, running multiple agents in parallel - you realize: understanding how you use AI is the first step to using it better.
Both tools read directly from local log files that Claude Code writes automatically during operation, stored at ~/.claude/projects/. No data is sent anywhere, no additional service connections needed.
Why track Claude Code usage?
Claude Code with a Max or Pro subscription doesn’t charge per token - but there are limits within each 5-hour billing window. If you hit the limit exactly when you’re in the middle of an important task, the experience is quite painful.
Tracking usage helps you:
- Know if you have room left - before starting a heavy task, check how much is left in the current 5-hour block
- Spot expensive patterns - which sessions, tasks, or models are consuming the most tokens
- Optimize your workflow - if 80% of your cost comes from one specific type of task, you can adjust how you approach it
- Calculate actual costs - especially important if you’re on pay-as-you-go or considering upgrading your plan
ccusage - Simple CLI, clear data
GitHub: ryoppippi/ccusage
ccusage is a CLI tool built by ryoppippi from the open-source community. The best part: no installation needed, runs directly with npx.
Run instantly, no install
npx ccusage@latestAlways use @latest to ensure you have the newest version with pricing data updated from LiteLLM.
Main commands
| Command | Description |
|---|---|
npx ccusage@latest | Daily report (default) |
npx ccusage@latest daily | Tokens and cost per day |
npx ccusage@latest monthly | Monthly summary |
npx ccusage@latest session | Detail by conversation session |
npx ccusage@latest blocks | Breakdown by 5-hour billing window |
The blocks command is especially useful - it maps directly to how Claude Code calculates usage, showing you exactly how much you’ve consumed within each 5-hour window.
Filtering and customization
# View usage from a specific date
npx ccusage@latest daily --since 2026-04-01
# View within a date range
npx ccusage@latest daily --since 2026-04-01 --until 2026-04-15
# Breakdown by model
npx ccusage@latest daily --breakdown
# Export to JSON for further processing
npx ccusage@latest monthly --json
# Filter by specific project
npx ccusage@latest daily --project project-name
# Run offline (uses pricing cache, no internet needed)
npx ccusage@latest --offlineReading the output
When you run npx ccusage@latest daily, you see a table with these columns:
- Date: The date
- Input tokens: Tokens you sent in (prompt + context)
- Output tokens: Tokens Claude returned
- Cache read / Cache write: Tokens that were cached - this is the “savings” column
- Cost ($): Cost converted using LiteLLM pricing
Tip: A large Cache read column is a good sign - it means you’re taking advantage of prompt caching, which meaningfully reduces your actual cost.
MCP integration (advanced)
ccusage has a built-in MCP server, letting you ask Claude about your own usage directly in a conversation:
npx ccusage@latest mcpThen configure it in Claude Code to use as a tool. The idea: “Hey Claude, how much have I used this week?” - and Claude replies with real data from your local logs.
codeburn - More visual TUI dashboard
GitHub: AgentSeal/codeburn
If ccusage is a table of numbers, codeburn is a dashboard with an interface - running right inside your terminal with charts, panels, and keyboard navigation.
Installation
npm install -g codeburnRequires Node.js 20+. Install once, use indefinitely.
Running it
codeburnOpen terminal, type the command, dashboard renders immediately. No additional config.
What codeburn shows
Gradient charts over time Token and cost charts by day and week - much easier to visualize trends than staring at raw numbers.
Task classification (13 categories) codeburn automatically classifies tasks based on tool usage patterns and keywords in your messages - no LLM calls, fully deterministic. You can see what you use Claude Code for most: code generation, debugging, editing, testing, documentation, and so on.
This is a genuinely interesting insight. Many people assume they use AI to write code, but looking at the dashboard reveals that 60% of their time is actually spent debugging and explaining code to AI.
One-shot success rate The rate at which Claude gets it right on the first try versus how many times you need to edit or retry. Use this metric to understand which tasks AI nails and which tasks need better prompting or more context.
Multi-provider support Supports both Claude Code and Codex (OpenAI) if you use both.
macOS Menu Bar (bonus)
codeburn ships with a SwiftBar plugin - displays today’s cost right in the macOS menu bar with a fire icon. Install SwiftBar, copy the plugin in, and you’re done. Glance at the top of your screen to see how much you’ve spent today.
Quick comparison: Which one to use?
| Criteria | ccusage | codeburn |
|---|---|---|
| Interface | Terminal text table | TUI dashboard with charts |
| Installation | Not needed (npx) | Global install |
| Data filtering | Many flexible filters | Keyboard navigation |
| JSON export | Yes (--json) | Not built-in |
| Task classification | No | Yes (13 categories) |
| macOS menu bar | No | Yes (SwiftBar) |
| MCP integration | Yes | No |
| Node.js requirement | Any version | 20+ |
Practical recommendation: Use both. ccusage for quickly checking specific numbers (“how much did I use this week?”, “does this 5-hour block have room left?”). codeburn for an overall visual view and analyzing weekly work patterns.
Suggested practical workflow
Morning before you start:
npx ccusage@latest blocksCheck the current 5-hour block - how much room is left to plan your morning.
End of week review:
npx ccusage@latest monthly --breakdownSee total monthly cost, broken down by model to see whether you’re using claude-opus or sonnet more.
When you want deeper analysis:
codeburnOpen the dashboard, view task classification, identify which workflows are “burning” the most tokens and adjust for the coming month.
FAQ
Are these tools safe? Is any data sent externally?
Both tools read directly from local JSONL files at ~/.claude/projects/ on your machine. There are no external API calls, no login required, no data sent to any server. Fully local-first and open-source - you can read the source code to verify.
Where does Claude Code store logs? Can I view them directly?
Claude Code automatically writes logs to ~/.claude/projects/ - each conversation session is a separate .jsonl file. You can open them in a text editor to see the raw data, but the format is fairly complex. ccusage and codeburn parse and aggregate these files into a readable form.
I use Claude Code with a Pro/Max subscription. Do I need to care about cost?
With a subscription, you aren’t charged per token - but you should still track usage to understand how the 5-hour billing window works. If you hit the limit right in the middle of an important task, you have to wait. Use the blocks command to check before starting heavy tasks.
ccusage shows "no data found" - why?
Claude Code needs to have been used at least once to create log files. If you just installed Claude Code and haven’t run any sessions yet, there’s no data. Try running again after you’ve had at least one conversation session.
Summary
ccusage and codeburn are two small but genuinely useful tools for anyone who uses Claude Code regularly. Both are open-source, local-first, and set up in minutes.
- Use ccusage when you need quick numbers, filtering by date/month/project, or want MCP integration
- Use codeburn when you want a complete visual overview and want to analyze work patterns
Understanding how you use AI is the first step to using it better. You don’t need to check every day - but a weekly review will help you spot areas to optimize and work more effectively with Claude Code.