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:

| Source | Tool | Data location | | ---------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | claude | Claude Code | ~/.claude/projects/ (JSONL) | | droid | Factory Droid | ~/.factory/sessions/ (JSONL) | | zcode | ZCode (Zai's coding tool) | ~/.zcode/cli/db/db.sqlite | | codex | OpenAI Codex CLI | ~/.codex/sessions/ (JSONL) | | opencode | OpenCode | ~/.local/share/opencode/opencode.db | | devin | Devin (Cognition) | ~/.local/share/devin/cli/transcripts/ + sessions.db | | pi | pi + 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

Quick Start (Recommended)

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.

Related Tools

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

| Feature | ccusage | better-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

License

MIT © @cobra91