Stop Burning Cash on AI Coding Agents! Track Every Token with ccusage

Stop Burning Cash on AI Coding Agents! Track Every Token with ccusage

Here's a dirty secret most developers won't admit: they have no idea how much they're spending on AI coding agents. You fire up Claude Code, blaze through a three-hour refactoring session, and feel like a productivity god—until your Anthropic invoice lands in your inbox. Suddenly that "quick fix" cost you $47. Last month? You blew past $300 without noticing. Sound familiar?

The AI coding revolution has a hidden tax, and it's bleeding developers dry. Claude Code, OpenAI's Codex, OpenCode, Amp, pi-agent—these tools are incredible, but they're also black boxes of burning money. No built-in cost dashboards. No real-time warnings. Just silent token consumption that compounds into shocking bills.

What if you could see every penny in real-time? What if you could track daily spending, spot expensive sessions, and actually optimize how you use these agents?

Enter ccusage—the open-source CLI tool that's exposing what no one else will show you. Created by ryoppippi, this ultra-lightweight analyzer reads your local agent data and transforms it into beautiful, actionable cost reports. No API keys. No cloud uploads. Your data never leaves your machine.

In this deep dive, I'll show you why ccusage went viral, how it clawed back hundreds of dollars for developers, and exactly how to wield it like a financial weapon. Let's stop the bleeding.

What is ccusage? The Cost Transparency Tool AI Vendors Hope You Never Find

ccusage is a blazing-fast CLI utility that analyzes token usage and costs from locally-stored AI coding agent data. Born from the very real pain of unpredictable AI bills, it supports Claude Code, Codex, OpenCode, Amp, and pi-agent—unifying what would otherwise be five separate monitoring headaches into one elegant interface.

The brainchild of Japanese developer ryoppippi, ccusage exploded in popularity after a viral YouTube feature dubbed it "The Claude Code cost scorecard that went viral." But this isn't hype-driven vaporware. The project's Trendshift badge and accelerating npm download graph tell the real story: developers are desperate for this.

Why now? Because AI coding agents crossed an inflection point in 2024-2025. Claude Code's agentic loop—autonomously reading files, running commands, iterating on solutions—consumes tokens at rates that make traditional ChatGPT usage look like pocket change. A single complex task can burn through 500K+ tokens. Without visibility, you're flying blind into a financial storm.

cusage solves this with zero configuration overhead and radical transparency. It reads the local databases these agents already create—no instrumentation, no proxies, no API integration required. The result? Instant cost awareness that changes how you code.

The project's philosophy is equally refreshing: extreme bundle size optimization. While competitors ship megabytes of dependencies, ccusage prides itself on being "incredibly small even without minification." This matters when you're running it dozens of times daily.

Key Features That Make ccusage Irreplaceable

Let's dissect what makes this tool so addictive for cost-conscious developers:

📊 Multi-Timeframe Analytics — Slice your data by day, week, month, or individual session. The blocks command reveals Claude Code's 5-hour billing windows, exposing how Anthropic actually charges you. This is secret knowledge most developers never access.

🤖 Universal Agent Support — One CLI for Claude Code, Codex, OpenCode, Amp, and pi-agent. No context-switching between vendor tools. The --mode display and --speed fast flags let you customize per-source behavior.

💰 Granular Cost Tracking — See USD costs per day, month, session, or project. The --breakdown flag splits costs by model (Claude 3.5 Sonnet vs. Opus, etc.), revealing which models drain your budget fastest.

🔄 Cache Token Intelligence — Most tools ignore cache creation and cache read tokens. ccusage surfaces these separately, showing how effectively you're leveraging Anthropic's caching discounts. This alone can save 30-40% on costs.

🏗️ Project-Level Grouping — The --instances flag groups Claude Code usage by project, while --project myproject filters to specific codebases. Finally, you can attribute costs to actual work, not just vague "development time."

📱 Adaptive Display — Smart tables automatically compact for narrow terminals (<100 characters), while --compact forces screenshot-friendly layouts. The statusline command (Beta) embeds live cost data into your editor status bar.

🌐 True Offline Operation — Pre-cached pricing data means --offline works without network. Analyze costs on planes, in secure environments, or during outages.

⚙️ Configuration File Support — JSON config files with IDE autocomplete and validation eliminate repetitive flags. Set your timezone, default sources, and output preferences once.

🚀 Bun-Optimized Performance — Automatically detects and re-runs under Bun for faster warm starts. The CCUSAGE_BUN_AUTO_RUN=0 escape hatch preserves Node.js when needed.

5 Brutal Real-World Use Cases Where ccusage Pays for Itself

1. The Freelancer's Invoice Justification

You're billing clients for AI-assisted development, but "Claude Code subscription" doesn't explain $200 in variable costs. ccusage generates timestamped, project-filtered reports that prove exactly which work consumed which tokens. Attach --json exports to invoices. Stop eating costs that should be billable.

2. The Team Lead's Budget Defense

Your engineering manager questions the $2,000/month "AI tools" line item. With ccusage monthly --all --breakdown, you present beautiful tables showing per-developer, per-project, per-model consumption. Convert vague anxiety into data-driven budget conversations.

3. The Optimization Detective

One developer's costs are 3x higher than the team's. ccusage session reveals they're running Claude Code on enormous files without caching, triggering redundant full-context reloads. A 10-minute workflow fix saves $150/month. You can't optimize what you can't measure.

4. The Billing Window Strategist

Claude Code's 5-hour blocks reset pricing tiers. ccusage blocks shows active windows and consumption patterns. Time your heaviest agentic sessions to maximize value within each block. This is advanced cost arbitrage that vendor documentation buries.

5. The Offline Security Auditor

In air-gapped environments or during compliance reviews, --offline analyzes historical data without external calls. Prove cost controls to auditors, identify anomalous usage patterns, and maintain security posture. Compliance and transparency, finally compatible.

Step-by-Step Installation & Setup Guide

ccusage's installation is intentionally frictionless. Here's every path to get running:

Zero-Install Quick Start (Recommended)

The tool is so lightweight, you often don't need to install it at all:

# Recommended: Bun execution (fastest warm performance)
bunx ccusage

# Alternative package runners
pnpm dlx ccusage
pnpx ccusage
npx ccusage@latest  # Note: @latest required for npx

Critical Runtime Note: The published CLI shebang targets Node.js, so package runners initially launch under Node. However, ccusage automatically detects bun in your PATH and re-runs its bundled entrypoint with Bun for superior performance. To force Node.js execution, set CCUSAGE_BUN_AUTO_RUN=0.

System Requirements

• Node.js 22+ (when using npx)
• Bun (optional, for optimized execution)
• Local data from supported agents (Claude Code, Codex, etc.)

Global Installation

For frequent use, install permanently:

# Via npm
npm install -g ccusage

# Via Bun
bun add -g ccusage

# Via pnpm
pnpm add -g ccusage

Development Setup (Contributors)

For those hacking on ccusage itself, a Nix flake guarantees reproducible environments:

# Clone the repository
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Automatic environment via direnv
direnv allow

# Or manual Nix shell
nix develop

This ensures identical Node.js, Bun, and tooling versions across all contributors and CI pipelines.

Configuration Files

Create .ccusagerc.json or ccusage.config.json for persistent defaults:

{
  "timezone": "America/New_York",
  "defaultSource": "claude",
  "compact": false,
  "offline": false
}

IDE autocomplete and JSON schema validation are built-in. No more typing --timezone UTC every invocation.

REAL Code Examples: Master ccusage Like a Pro

Let's walk through actual commands from the repository, explaining exactly what each reveals and when to use it.

Example 1: The Daily Cost Pulse Check

# Show all detected sources aggregated by day (default behavior)
bunx ccusage

# Equivalent explicit commands
bunx ccusage daily        # All sources, daily grouping
bunx ccusage weekly       # All sources, weekly grouping  
bunx ccusage monthly      # All sources, monthly grouping
bunx ccusage session      # All sources, session grouping

When to use: Start every morning with bunx ccusage daily. This is your financial vital sign—a quick scan of yesterday's burn rate. I run this in my shell's .bashrc equivalent so it's visible when I open my terminal. The default behavior auto-detects all supported agents, so if you run Claude Code and Codex side-by-side, both appear in unified tables.

The weekly and monthly variants are essential for pattern recognition. Is your Tuesday always expensive? That's likely your standup-driven refactoring day. Monthly views expose subscription vs. usage-based cost ratios.

Example 2: Source-Specific Deep Dives with Options

# Claude Code with display mode (shows richer output)
bunx ccusage claude daily --mode display

# Codex with fast speed optimization (lighter analysis, quicker results)
bunx ccusage codex daily --speed fast

# OpenCode weekly aggregation
bunx ccusage opencode weekly

# Amp session-level detail
bunx ccusage amp session

# pi-agent with custom data path
bunx ccusage pi daily --pi-path /path/to/sessions

# Multiple pi-agent paths (comma-separated)
bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions

When to use: These commands target single-source precision. The --mode display flag for Claude Code renders enhanced visual output—critical when presenting to stakeholders. --speed fast sacrifices some analysis depth for near-instant results; perfect when you're about to start a new session and need a 2-second cost snapshot.

The --pi-path flexibility matters because pi-agent stores sessions in configurable locations. The comma-separated syntax lets you aggregate archived and active data—essential for long-term historical analysis without moving files.

Example 3: Advanced Filtering and Export

# Date range filtering for precise investigation
bunx ccusage daily --since 2026-04-25 --until 2026-05-16

# JSON export for programmatic consumption
bunx ccusage daily --json

# UTC timezone normalization (critical for distributed teams)
bunx ccusage daily --timezone UTC

# Explicit unified report across all sources
bunx ccusage daily --all

When to use: Date filtering is your forensic tool. When a bill spikes unexpectedly, --since and --until isolate the incident window. I've used this to prove a "simple bug fix" actually triggered 12 hours of agentic iteration.

--json transforms ccusage from a pretty-printer into a data pipeline component. Pipe to jq, ingest into monitoring systems, or automate Slack alerts when daily costs exceed thresholds. The schema is stable and documented at ccusage.com.

UTC normalization prevents the midnight boundary nightmare. When your team spans timezones, local-midnight grouping creates inconsistent daily totals. --timezone UTC ensures everyone's "Tuesday" is identical.

Example 4: Project-Aware Cost Attribution

# Group Claude Code usage by project/instance
bunx ccusage claude daily --instances

# Filter to specific project only
bunx ccusage claude daily --project myproject

# Combined: project-filtered with instance grouping and JSON export
bunx ccusage claude daily --instances --project myproject --json

When to use: This is enterprise-grade cost allocation in a single command. --instances reveals how Claude Code's workspace detection segments your work—crucial when you context-switch between client projects. Without this, costs from "Project A" and "Project B" blur into an unusable aggregate.

The combined example—--instances --project myproject --json—generates machine-readable, project-isolated reports. I automate this in CI to append cost summaries to project documentation after major refactors.

Example 5: Claude Code Billing Window Intelligence

# Track usage within Claude's 5-hour billing windows
bunx ccusage blocks

# Status line integration for editor hooks (Beta)
bunx ccusage statusline

# Force compact mode for screenshots/sharing
bunx ccusage --compact
bunx ccusage monthly --compact

When to use: The blocks command exposes Anthropic's actual pricing mechanics. Claude Code charges in 5-hour windows—understanding your consumption within each window reveals whether you're efficiently utilizing your tier or wastefully triggering new block initiations.

statusline is for ambient awareness. Embed in Vim, Emacs, or VS Code status bars to see live cost context without leaving your editor. The Beta label means the interface may evolve—pin your version in production workflows.

--compact is social media^{↗ Bright Coding Blog} optimization. Those beautiful Twitter screenshots of "I spent $X this month on AI"? They're compact mode. Essential columns only, clean layout, instant shareability.

Advanced Usage & Best Practices

The Morning Ritual

Add to your shell profile:

# Daily cost awareness on terminal open
bunx ccusage daily --compact 2>/dev/null || true

This surfaces costs without blocking your workflow. The 2>/dev/null || true ensures clean failure if offline.

The Pre-Commit Hook

Prevent expensive accidental commits of generated files:

# In .git/hooks/pre-commit or Husky
COST=$(bunx ccusage daily --json | jq '.[0].costUSD // 0')
if (( $(echo "$COST > 50" | bc -l) )); then
  echo "WARNING: Today's AI costs exceed \$50. Proceed? [y/N]"
  read -r response
  [[ "$response" =~ ^[Yy]$ ]] || exit 1
fi

The Weekly Report Automation

# Cron job for Monday morning team reports
0 9 * * 1 cd /home/dev && bunx ccusage weekly --all --json > /var/reports/ai-costs-$(date +\%Y\%m\%d).json

Cache Optimization Workflow

Run ccusage claude daily --breakdown weekly. If cache read tokens are low relative to total, you're not leveraging context caching. Restructure your prompts to reuse context across related tasks.

Comparison with Alternatives

The verdict: Manual tracking fails at scale. Vendor dashboards lack cross-agent visibility and hide pricing mechanics. Custom scripts become maintenance nightmares. ccusage occupies the sweet spot of zero-config, deep insight, and radical transparency.

FAQ: Your Burning Questions Answered

Q: Does ccusage send my code or usage data anywhere? A: Absolutely not. ccusage reads local files already stored by your AI agents. No network requests, no telemetry, no cloud processing. Your proprietary code never leaves your machine.

Q: Which AI coding agents are supported? A: Claude Code, OpenAI Codex, OpenCode, Amp, and pi-agent. The unified CLI means one tool replaces multiple vendor-specific monitors.

Q: Do I need API keys or Anthropic account access? A: No. ccusage analyzes local data files that agents create automatically. No authentication, no rate limits, no permissions to configure.

Q: How accurate are the cost calculations? A: Costs use pre-cached pricing data updated with each release. The --offline flag uses this cached data. For absolute precision, ensure you're on the latest ccusage version when pricing changes occur.

Q: Can I export data to Excel or Google Sheets? A: Use --json and pipe to tools like jq or Python^{↗ Bright Coding Blog} scripts. The JSON schema is stable and documented. Community converters for Excel/Sheets are emerging.

Q: What's the performance impact of running ccusage frequently? A: Negligible. The ultra-small bundle and Bun optimization mean sub-second execution. Many users run it in shell startup files without noticing.

Q: Is there a GUI version or web interface? A: Currently CLI-only, which enables the speed and portability that make ccusage powerful. The --compact and statusline features address common GUI desires. Follow the GitHub repo for future developments.

Conclusion: Take Back Control of Your AI Spending

The AI coding agent revolution is here to stay, but uncontrolled token consumption is not inevitable. ccusage transforms the opaque into the obvious—the hidden cost sink into visible, optimizable data.

What started as ryoppippi's personal frustration has become essential infrastructure for developers serious about sustainable AI adoption. The viral growth, the Trendshift momentum, the obsessive attention to bundle size—all signal a tool built by someone who actually lives this problem daily.

Stop treating AI costs as mysterious forces of nature. Start treating them as measurable, manageable engineering decisions. Install ccusage in ten seconds, run your first report, and feel that immediate shift from anxiety to awareness.

Your move:

bunx ccusage daily

Then star the repo, share your savings story, and join the growing community of developers who refuse to fly blind.

→ Get ccusage on GitHub
→ Full documentation at ccusage.com

The age of AI cost transparency starts now. Don't be the developer still shocked by next month's bill.