🚀 A high-performance Go implementation of Claude Code usage analyzer

Installation • Usage • Features • Comparison • 繁體中文

Real-time token usage monitoring with gradient progress bars

ccusage_go is a Go implementation of the popular ccusage tool by @ryoppippi. This version maintains compatibility with the original TypeScript version while offering significant performance improvements and reduced memory footprint.

Test environment: macOS, Apple Silicon, monitoring 10+ projects, 15-second measurements after 5s warmup †CPU: Go version has higher peak during initial file loading but drops to <10% during monitoring

Note on Download Size: While the ccusage npm package is only ~1 MB, it requires Node.js runtime (~100 MB) to be pre-installed. The ccusage_go binary is completely self-contained at 3.5-4 MB compressed, requiring no runtime or dependencies.

Performance Testing: The above measurements were obtained using our monitoring script (docs/monitor_ccusage.sh) which tracks all child processes including Node.js runtime. You can reproduce these tests with:

# Monitor ccusage (TypeScript version)
./docs/monitor_ccusage.sh

# Monitor ccusage_go
./docs/monitor_ccusage.sh ccusage_go

• Ultra-Compact: Only 3.5-4 MB download (compressed)
• Single Binary: ~10 MB executable, no runtime required
• Zero Dependencies: No Node.js, npm, or any other dependencies
• Instant Start: Direct execution without installation process
• Cross-Platform: Native binaries for all major platforms

# Clone the repository
git clone https://github.com/SDpower/ccusage_go.git
cd ccusage_go

# Build
make build

# Install to system
make install

Download from GitHub Releases

# macOS Apple Silicon
curl -L https://github.com/SDpower/ccusage_go/releases/download/v0.11.1/ccusage_go-darwin-arm64.tar.gz | tar xz
sudo mv ccusage_go-darwin-arm64 /usr/local/bin/ccusage_go

# macOS Intel
curl -L https://github.com/SDpower/ccusage_go/releases/download/v0.11.1/ccusage_go-darwin-amd64.tar.gz | tar xz
sudo mv ccusage_go-darwin-amd64 /usr/local/bin/ccusage_go

# Linux x64
curl -L https://github.com/SDpower/ccusage_go/releases/download/v0.11.1/ccusage_go-linux-amd64.tar.gz | tar xz
sudo mv ccusage_go-linux-amd64 /usr/local/bin/ccusage_go

# Daily usage report
./ccusage_go daily

# Monthly summary
./ccusage_go monthly

# Session-based analysis
./ccusage_go session

# 5-hour billing blocks
./ccusage_go blocks

# Live monitoring (with gradient progress bars!)
./ccusage_go blocks --live

# Filter by date range
./ccusage_go daily --since 2025-01-01 --until 2025-01-31

# Different output formats
./ccusage_go monthly --format json
./ccusage_go session --format csv

# Custom timezone
./ccusage_go daily --timezone America/New_York

# Show only recent activity
./ccusage_go blocks --recent

While ccusage's npm package is smaller (1 MB), it requires Node.js runtime. The ccusage_go provides a complete solution in a single 3.5-4 MB download with 87% less memory usage and 92% less CPU usage during operation.

• 📊 Daily Reports: Token usage and costs per day
• 📈 Monthly Reports: Aggregated monthly statistics
• 💬 Session Analysis: Usage by conversation session
• ⏱️ Billing Blocks: 5-hour billing window tracking
• 🔴 Live Monitoring: Real-time usage dashboard with gradient progress bars
• 📊 Usage Limits: Live display of Claude API quota (session/weekly limits)
• 🎨 Multiple Output Formats: Table (default), JSON, CSV
• 🌍 Timezone Support: Configurable timezone for reports
• 💾 Offline Mode: Works without internet connection
• 🚀 Parallel Processing: Fast data loading with goroutines
• 🎯 Memory Efficient: Streaming JSONL processing

• Gradient Progress Bars: Smooth color transitions in LUV color space
• Enhanced TUI: Built with Bubble Tea framework
• Performance Caching: Optimized rendering with color caching
• "WITH GO" Branding: All reports clearly marked as Go version
• Unified Model Labels: Support for latest Claude model formats (Opus-4.6, Sonnet-4.6, Opus-4.5, Sonnet-4.5, Haiku-4.5)

• Language: Go 1.23+
• CLI Framework: Cobra
• TUI Framework: Bubble Tea
• Table Rendering: tablewriter
• Styling: Lip Gloss
• Color Gradients: go-colorful

• Go 1.23 or higher
• Make (optional, for convenience)

# Basic build
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run with profiling
ENABLE_PROFILING=1 go test -v ./...

ccusage_go/
├── cmd/ccusage/        # CLI entry point
├── internal/           # Core implementation
│   ├── calculator/     # Cost calculation logic
│   ├── commands/       # CLI command handlers
│   ├── loader/         # Data loading and parsing
│   ├── monitor/        # Live monitoring features
│   ├── output/         # Formatting and display
│   ├── pricing/        # Price fetching and caching
│   ├── types/          # Type definitions
│   └── usage/          # Claude API usage limits
├── docs/               # Documentation
└── test_data/          # Test fixtures

1. Large Datasets: The Go version uses streaming and parallel processing for optimal performance
2. Memory Optimization: Implements smart file filtering, only loading projects active within 12 hours
3. Live Monitoring: Gradient calculations are cached for smooth real-time updates
4. Resource Usage: blocks --live mode uses only ~54MB memory with minimal system impact
5. Incremental Cache: Project-level caching in live mode reduces CPU usage by 68% when data is unchanged

• 🙏 Original ccusage by @ryoppippi
• 🎨 Bubble Tea for the beautiful TUI framework
• 💙 All contributors and users

MIT © @SteveLuo

Contributions are welcome! Please feel free to submit a Pull Request.

• Implement remaining TypeScript features
• Add pre-built binaries for major platforms
• Enhance MCP integration
• Add more customization options
• Implement --project and --instances filters
• Add internationalization support

Made with ❤️ in Go