Project analysis

May 26, 2026 · View on GitHub

better-ccusage logo

better-ccusage

npm version npm downloads install size zread Ask DeepWiki ClaudeLog - A comprehensive knowledge base for Claude. CodeRabbit Pull Request Reviews

Analyze your Claude Code, Droid, ZCode, Codex, OpenCode, Devin, and pi/oh-my-pi token usage and costs from local JSONL/SQLite files with multi-provider support — incredibly fast and informative!

About better-ccusage

better-ccusage is an enhanced fork of the ccusage project. It aggregates token usage and costs across seven local AI coding tools into a single report, with broad multi-provider pricing support.

Supported data sources

better-ccusage reads usage data directly from each tool's local files (JSONL or SQLite), auto-detected from their default locations:

SourceToolData location
claudeClaude Code~/.claude/projects/ (JSONL)
droidFactory Droid~/.factory/sessions/ (JSONL)
zcodeZCode (Zai's coding tool)~/.zcode/cli/db/db.sqlite
codexOpenAI Codex CLI~/.codex/sessions/ (JSONL)
opencodeOpenCode~/.local/share/opencode/opencode.db
devinDevin (Cognition)~/.local/share/devin/cli/transcripts/ + sessions.db
pipi + oh-my-pi~/.pi/agent/sessions/ + ~/.omp/agent/sessions/ (auto-detected, JSONL)

Filter to a single source with the positional syntax: better-ccusage <source> <report> (e.g. better-ccusage devin daily).

Why the fork?

The original ccusage project focused exclusively on Claude Code usage with Anthropic models. better-ccusage extends this in two directions:

  • Multi-source: added ZCode (SQLite), Droid, OpenAI Codex, OpenCode, Devin, and pi/oh-my-pi on top of Claude Code — all aggregated in one report. (Devin and pi are ported from upstream ccusage's open PRs #1398 and #1338; better-ccusage ships them ahead of upstream.)
  • Multi-provider pricing: accurate cost calculation for external providers that run Claude Code with their own models — Anthropic, Zai (all GLM models including GLM-5-Turbo, GLM-5.2), Dashscope, Kwaipilot (kat-coder), Moonshot (kimi), Minimax, Qwen-Max, and more.

Note: better-ccusage and upstream ccusage have diverged significantly in architecture and scope. better-ccusage is a TypeScript monorepo; upstream ccusage is a Rust workspace. They are maintained independently — feature ports go in both directions but are not kept in lockstep.

better-ccusage Family

📊 better-ccusage - Enhanced Claude Code/Droid/ZCode/Codex/OpenCode/Devin/pi Usage Analyzer with Multi-Provider Support

The main CLI tool for analyzing Claude Code, Droid, ZCode, OpenAI Codex, OpenCode, Devin, and pi/oh-my-pi usage from local JSONL/SQLite files with support for multiple AI providers including Anthropic, Zai, and all GLM models (including GLM-5-Turbo, GLM-5.2), kat-coder models. Track daily, weekly, monthly, and session-based usage with beautiful tables and live monitoring. ZCode usage is read directly from its SQLite database (~/.zcode/cli/db/db.sqlite), Codex usage from ~/.codex/sessions, OpenCode usage from ~/.local/share/opencode/opencode.db, Devin usage from ATIF transcripts under ~/.local/share/devin/cli/transcripts/ (enriched by sessions.db), and pi/oh-my-pi usage from JSONL sessions under ~/.pi/agent/sessions and ~/.omp/agent/sessions (auto-detected).

💡 The standalone @better-ccusage/codex and @better-ccusage/opencode packages are now deprecated forwarders — Codex and OpenCode support is built directly into better-ccusage. Run npx better-ccusage to see all sources in one report.

🔌 @better-ccusage/mcp - MCP Server Integration

Model Context Protocol server that exposes better-ccusage data to Claude Desktop and other MCP-compatible tools. Enable real-time usage tracking directly in your AI workflows.

Installation

Thanks to better-ccusage's incredibly small bundle size, you can run it directly without installation:

# Recommended - always include @latest to ensure you get the newest version
npx better-ccusage@latest
bunx better-ccusage

# Alternative package runners
pnpm dlx better-ccusage
pnpx better-ccusage

# Using deno (with security flags)
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:better-ccusage@latest

💡 Important: We strongly recommend using @latest suffix with npx (e.g., npx better-ccusage@latest) to ensure you're running the most recent version with the latest features and bug fixes.

MCP Server

Integrate better-ccusage with Claude Desktop using @better-ccusage/mcp:

# Start MCP server for Claude Desktop integration
npx @better-ccusage/mcp@latest --type http --port 8080

This enables real-time usage tracking and analysis directly within Claude Desktop conversations.

Usage

# Basic usage
npx better-ccusage          # Show daily report (default)
npx better-ccusage daily    # Daily token usage and costs
npx better-ccusage weekly   # Weekly aggregated report
npx better-ccusage monthly  # Monthly aggregated report
npx better-ccusage session  # Usage by conversation session
npx better-ccusage blocks   # 5-hour billing windows
npx better-ccusage statusline  # Compact status line for hooks (Beta)

# Live monitoring
npx better-ccusage blocks --live  # Real-time usage dashboard

# Filters and options
npx better-ccusage daily --since 20250525 --until 20250530
npx better-ccusage daily --json  # JSON output
npx better-ccusage daily --breakdown  # Per-model cost breakdown
npx better-ccusage daily --timezone UTC  # Use UTC timezone
npx better-ccusage daily --locale ja-JP  # Use Japanese locale for date/time formatting

# Project analysis
npx better-ccusage daily --instances  # Group by project/instance
npx better-ccusage daily --project myproject  # Filter to specific project
npx better-ccusage daily --instances --project myproject --json  # Combined usage

# Compact mode for screenshots/sharing
npx better-ccusage --compact  # Force compact table mode
npx better-ccusage monthly --compact  # Compact monthly report

# Focus on a single data source (Claude, Droid, ZCode, Codex, OpenCode, Devin, pi)
# By default every report aggregates all detected sources. Prefix the command
# with a source name to see usage for that tool only:
npx better-ccusage codex daily          # Codex-only daily report
npx better-ccusage opencode blocks      # OpenCode-only billing blocks
npx better-ccusage droid session        # Droid-only session report
npx better-ccusage devin daily          # Devin-only daily report
npx better-ccusage pi daily             # pi/oh-my-pi-only daily report
npx better-ccusage zcode monthly        # ZCode-only monthly report
npx better-ccusage codex                # shorthand for "codex daily"
# Equivalent explicit form (the positional form above is preferred):
npx better-ccusage daily --source codex

💡 Tip: Running better-ccusage <source> (e.g. better-ccusage codex) with no report defaults to daily, the same shorthand upstream ccusage uses.

Multi-Provider Support

better-ccusage extends the original ccusage functionality with automatic support for multiple AI providers:

🔄 Automatic Provider Detection

  • Zero Configuration Required: New providers work automatically without code changes
  • Intelligent Model Resolution: Finds models with or without provider prefixes
  • Fallback Matching: Three-tier matching (exact → suffix → fuzzy) ensures models are always found

How It Works:

  • Direct match: "kimi-for-coding" ✓
  • Provider prefix match: "moonshot/kimi-for-coding" ✓
  • Automatic fallback prevents $0.00 costs from unfound models

🚀 Supported AI Providers & Models

Moonshot AI (kimi-* models):

  • kimi-k2-0905-preview, kimi-k2-0711-preview, kimi-k2-turbo-preview
  • kimi-k2-thinking, kimi-k2-thinking-turbo, kimi-for-coding

MiniMax:

  • MiniMax-M2

All GLM Models

Anthropic (Claude models):

  • All Claude models including claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, etc.

Zai Provider:

  • All Zai-specific model variants like GLM-5

And More:

  • kat-coder, deepseek, dashscope, streamlake, etc.

🌐 Provider-Aware Analytics

  • Automatic provider detection from usage data
  • Separate reporting and aggregation by provider
  • Unified interface for multi-provider environments
  • Accurate cost calculation for each provider's pricing structure

Features

  • 📊 Daily Report: View token usage and costs aggregated by date
  • 📅 Weekly Report: View token usage and costs aggregated by week
  • 📆 Monthly Report: View token usage and costs aggregated by month
  • 💬 Session Report: View usage grouped by conversation sessions
  • ⏰ 5-Hour Blocks Report: Track usage within Claude's billing windows with active block monitoring
  • 📈 Live Monitoring: Real-time dashboard showing active session progress, token burn rate, and cost projections with blocks --live
  • 🚀 Statusline Integration: Compact usage display for Claude Code status bar hooks (Beta)
  • 🤖 Multi-Provider Model Tracking: Track models from Anthropic, Zai, Dashscope and other providers
  • 📊 Model Breakdown: View per-model cost breakdown with --breakdown flag
  • 📅 Date Filtering: Filter reports by date range using --since and --until
  • 📁 Custom Path: Support for custom Claude data directory locations
  • 🎨 Beautiful Output: Colorful table-formatted display with automatic responsive layout
  • 📱 Smart Tables: Automatic compact mode for narrow terminals (< 100 characters) with essential columns
  • 📸 Compact Mode: Use --compact flag to force compact table layout, perfect for screenshots and sharing
  • 📋 Enhanced Model Display: Model names shown as bulleted lists for better readability
  • 📄 JSON Output: Export data in structured JSON format with --json
  • 💰 Cost Tracking: Shows costs in USD for each day/month/session
  • 🔄 Cache Token Support: Tracks and displays cache creation and cache read tokens separately
  • 🔌 MCP Integration: Built-in Model Context Protocol server for integration with other tools
  • 🏗️ Multi-Instance Support: Group usage by project with --instances flag and filter by specific projects
  • 🌍 Timezone Support: Configure timezone for date grouping with --timezone option
  • 🌐 Locale Support: Customize date/time formatting with --locale option (e.g., en-US, ja-JP, de-DE)
  • ⚙️ Configuration Files: Set defaults with JSON configuration files, complete with IDE autocomplete and validation
  • 🚀 Ultra-Small Bundle: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!

Comparison with ccusage

Featureccusagebetter-ccusage
Anthropic Models✅✅
Moonshot (kimi) Models❌✅
MiniMax Models❌✅
GLM* Models❌✅
Zai Provider❌✅
kat-coder❌✅
Automatic Provider Detection❌✅
Multi-Provider Support❌✅
Cost Calculation by Provider❌✅
Original ccusage Features✅✅
Show prompt usage for Coding❌✅
Droid usage❌✅
ZCode usage❌✅
Codex usage❌✅
OpenCode usage❌✅
Devin usage❌✅
Per-source filtering❌✅

Star History

Star History Chart

License

MIT © @cobra91