better-ccusage

> Analyze your Claude Code or Droid token usage and costs from local JSONL files with multi-provider support — incredibly fast and informative!

About better-ccusage

better-ccusage is a fork of the original ccusage project that addresses a critical limitation: while ccusage focuses exclusively on Claude Code usage with Anthropic models, better-ccusage extends support to external providers that use Claude Code with different providers like Anthropic, Zai, Dashcope and many models like glm-4.5, glm-4.6, kat-coder, sonnet-4, sonnet-4.5 and Qwen-Max etc..

$3

The original ccusage project is designed specifically for Anthropic's Claude Code and doesn't account for:

- Zai providers that use Claude Code infrastructure with their own models
- GLM-4.5, GLM-4.6, GLM-4.7, kat-coder models from other AI providers
- Multi-provider environments where organizations use different AI services through Claude Code

better-ccusage maintains full compatibility with ccusage while adding comprehensive support for these additional providers and models.

better-ccusage Family

$3

The main CLI tool for analyzing Claude Code/Droid Usage from local JSONL files with support for multiple AI providers including Anthropic, Zai, and GLM-4.5, GLM-4.6, GLM-4.7, kat-coder models. Track daily, monthly, and session-based usage with beautiful tables and live monitoring.

$3

Companion tool for analyzing OpenAI Codex usage. Same powerful features as better-ccusage but tailored for Codex users, including GPT-5 support and 1M token context windows.

$3

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

$3

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

``bash


Recommended - always include @latest to ensure you get the newest version

> 💡 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.

$3

#### Codex CLI

Analyze OpenAI Codex usage with our companion tool @better-ccusage/codex:

`bash


Recommended - always include @latest

> ⚠️ Critical for bunx users: Bun 1.2.x's bunx prioritizes binaries matching the package name suffix when given a scoped package. For @better-ccusage/codex, it looks for a codex binary in PATH first. If you have an existing codex command installed (e.g., GitHub Copilot's codex), that will be executed instead. Always use bunx @better-ccusage/codex@latest with the version tag to force bunx to fetch and run the correct package.

#### MCP Server

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

`bash


Start MCP server for Claude Desktop integration

`bash


Basic usage

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

$3

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

GLM Models:
- glm-4.7, glm-4.6, glm-4.5, glm-4

Anthropic (Claude models):
- All Claude models including claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, etc.

Zai Provider:
- All Zai-specific model variants

And More:
- kat-coder, deepseek, dashscope, streamlake, etc.

$3

- 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
- 📅 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, Dashcope 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 | ❌ | ✅ |

Star History

License

MIT © @cobra91