ryoppippi/ccusage

★ 14,140TypeScriptAudience · developerComplexity · 2/5LicenseSetup · easy

Mindmap

mindmap
  root((ccusage))
    What it does
      Token usage reports
      Cost tracking
      Session analysis
    Sources supported
      Claude Code
      Codex Gemini CLI
      Copilot and more
    Report types
      Daily report
      Weekly report
      Monthly report
      Billing blocks
    Features
      JSON output
      Date filtering
      Project grouping
      Offline mode
    Tech stack
      TypeScript
      Node.js
      Nix flake

mindmap root((ccusage)) What it does Token usage reports Cost tracking Session analysis Sources supported Claude Code Codex Gemini CLI Copilot and more Report types Daily report Weekly report Monthly report Billing blocks Features JSON output Date filtering Project grouping Offline mode Tech stack TypeScript Node.js Nix flake

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Check how many tokens Claude Code used this week and how much it cost, without logging into any dashboard.

USE CASE 2

Export daily usage data as JSON to feed into a spreadsheet or cost-tracking script.

USE CASE 3

Monitor whether you are staying within Claude's five-hour billing windows using the blocks report.

USE CASE 4

Compare token costs across Claude Code, Codex, and Gemini CLI in one combined report.

Tech stack

TypeScriptNode.jsNix

Getting it running

Difficulty · easy Time to first run · 5min

MIT license: use freely for any purpose, including commercial, with no restrictions beyond keeping the copyright notice.

In plain English

ccusage is a command-line tool that reads the local usage logs that AI coding tools save to your computer and turns them into easy-to-read reports. If you use Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, or any of more than a dozen other AI coding assistants, ccusage can tell you exactly how many tokens each tool used and what those tokens cost in dollars, broken down by day, week, month, or conversation session. There is no account or API key required. The tool reads log files that already exist on your machine, produced by the AI tools you already run. A single command, npx ccusage@latest, is all it takes to see your first report. You can run focused reports for just one tool at a time, for example ccusage claude daily for Claude Code usage by day, or combine all detected tools into one unified view with ccusage daily. Reports show token counts for input, output, and cached tokens separately, along with costs in USD for each period. Filtering by date range is supported with date flags. A compact mode adjusts the table layout for narrow terminal windows, and a JSON output option lets you pipe the data into other scripts or dashboards. A dedicated blocks command tracks Claude's five-hour billing windows specifically, which is useful if you are trying to manage usage within a particular time period. The tool also supports grouping Claude Code usage by project folder with an instances flag, and lets you filter to a specific project. You can override pricing per model in a local config file without needing to rebuild the tool, and an offline mode avoids network calls by using pre-cached pricing data. ccusage is written in TypeScript and runs on Node.js. It can also be invoked from a Nix flake for reproducible use across different machines. It is MIT-licensed and open source.

Copy-paste prompts

Prompt 1

Show me how to use ccusage to see Claude Code token costs for the past 7 days, grouped by day.

Prompt 2

How do I export my ccusage report as JSON so I can track spending in a spreadsheet?

Prompt 3

I want to see how much I have spent on Claude Code this month by project. How do I use the instances flag?

Prompt 4

How do I configure ccusage with custom pricing overrides for a model that is not in the default pricing list?

Prompt 5

Set up ccusage to track my Claude 5-hour billing windows so I know when a new window starts.

Open on GitHub → Explain another repo

← ryoppippi on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.