ccstat

Analyze AI coding tool usage data from local log files.

Overview

ccstat is a high-performance Rust CLI tool that processes usage logs from multiple AI coding tools (Claude, Codex, OpenCode, Amp, Pi), calculates costs using LiteLLM pricing data, and provides various reporting views including daily, weekly, monthly, session-based, and 5-hour billing block reports.

This project is inspired by ccusage and is a Rust reimplementation (RIIR - Rewrite It In Rust) of the original TypeScript tool, offering:

• 50-70% reduction in memory usage
• 2-3x faster processing speed
• Zero memory leaks through RAII
• Better error handling and recovery

Features

• 🔌 Multi-Provider Support: Claude, Codex, OpenCode, Amp, and Pi Agent
• 📊 Multiple Report Types: Daily, weekly, monthly, session, and billing block views
• 💰 Accurate Cost Calculation: Uses latest LiteLLM pricing data with offline fallback
• 🔍 Automatic Discovery: Finds provider data directories across platforms
• 📈 Flexible Output: Table format for humans, JSON for machines
• 🚀 High Performance: Stream processing with minimal memory footprint
• 👀 Universal Live Monitoring: Real-time tracking with auto-refresh for ALL commands
• 📊 Live Billing Block Monitor: Visual ASCII art display with progress bars, burn rate, and projections
• 🎨 Watch Command Alias: Quick ccstat watch shortcut for live billing block monitoring
• 💸 Custom Cost Limits: Set your own maximum cost threshold for progress calculations
• ⚡ Performance Options: Parallel processing, string interning, arena allocation
• 🔧 Advanced Filtering: By date, project, instance, and more
• 🌍 Timezone Support: Accurate daily aggregation across different timezones
• 📊 Statusline Integration: Real-time usage monitoring for Claude Code status bar
• 🎯 Model Name Simplification: Shortened model names with --full-model-names option

Installation

From crates.io

The easiest way to install ccstat is using cargo:

cargo install ccstat

From Source

# Clone the repository
git clone https://github.com/hydai/ccstat
cd ccstat

# Build and install
cargo install --path .

Pre-built Binaries

Download the latest release for your platform from the releases page.

Docker

You can run ccstat using Docker without installing Rust or building from source:

# Pull the latest image
docker pull hydai/ccstat:latest

# Run ccstat with your Claude data directory mounted
docker run -v "$HOME/.claude:/data:ro" hydai/ccstat daily

# Use a specific version
docker run -v "$HOME/.claude:/data:ro" hydai/ccstat:v1.0.0 monthly

# Run with custom options
docker run -v "$HOME/.claude:/data:ro" hydai/ccstat daily --json --since 2024-01-01

For Linux users, the path is the same:

docker run -v "$HOME/.claude:/data:ro" hydai/ccstat daily

For Windows users (PowerShell):

docker run -v "$env:APPDATA\Claude:/data:ro" hydai/ccstat daily

The Docker image is multi-platform and supports both linux/amd64 and linux/arm64 architectures.

Quick Start

# View today's usage (defaults to daily command)
ccstat

# View with informational messages
ccstat --verbose

# View this month's usage
ccstat monthly

# View this week's usage
ccstat weekly

# View all sessions with costs
ccstat session

# Multi-provider support (default provider is claude)
ccstat codex daily               # Codex daily usage
ccstat opencode monthly          # OpenCode monthly usage
ccstat amp session               # Amp session analysis
ccstat pi daily                  # Pi Agent daily usage

# Show statusline for Claude Code integration
ccstat statusline

# Export data as JSON for further processing (global option)
ccstat --json > usage.json

# Live monitoring (works with all commands)
ccstat --watch                    # Watch daily usage (default)
ccstat monthly --watch            # Watch monthly aggregations
ccstat session --watch            # Watch active sessions
ccstat blocks --watch --active    # Visual live billing block monitor with progress bars

# Quick alias for live billing block monitor
ccstat watch                      # Same as blocks --watch --active
ccstat watch --max-cost 150       # Set custom $150 limit for progress bars

Usage

Daily Usage Report

Show daily token usage and costs. The daily command is the default when no command is specified.

# Default table output (these are equivalent)
ccstat
ccstat daily

# Common options can be used globally or with commands
ccstat --json                               # JSON output (global)
ccstat daily --json                         # JSON output (command-specific, backward compatible)

# Filter by date range (accepts YYYY-MM-DD or YYYY-MM format)
ccstat --since 2024-01-01 --until 2024-01-31
ccstat --since 2024-01                      # From January 2024

# Daily-specific options
ccstat daily --instances                    # Show per-instance breakdown
ccstat daily --detailed                     # Show detailed token info

# Live monitoring (global option, works with all commands)
ccstat --watch                              # Watch daily usage (default)
ccstat --watch --interval 30                # Custom refresh interval

# Global options work with all commands
ccstat --project my-project                 # Filter by project
ccstat --timezone "America/New_York"        # Use specific timezone
ccstat --utc                                # Force UTC timezone
ccstat --full-model-names                   # Show full model names

# Performance options (global)
ccstat --intern                             # Use string interning
ccstat --arena                              # Use arena allocation

Monthly Summary

Aggregate usage by month:

# Monthly totals
ccstat monthly

# Filter specific months (accepts YYYY-MM-DD or YYYY-MM format)
ccstat monthly --since 2024-01-01 --until 2024-03-31
ccstat monthly --since 2024-01 --until 2024-03  # Also works

# Live monitoring
ccstat monthly --watch                      # Watch monthly aggregations
ccstat monthly --watch --interval 10        # Custom refresh interval

# JSON output
ccstat monthly --json

# Filter by project
ccstat monthly --project my-project

# Timezone configuration
ccstat monthly --timezone "Asia/Tokyo"      # Use specific timezone
ccstat monthly --utc                        # Force UTC timezone

# Model display options
ccstat monthly --full-model-names           # Show full model names

Weekly Summary

Aggregate usage by week:

# Weekly totals (weeks start on Sunday by default)
ccstat weekly

# Custom start day
ccstat weekly --start-of-week monday

# With date filtering and JSON output
ccstat weekly --since 2025-01-01 --json

# Live monitoring
ccstat weekly --watch

Session Analysis

Analyze individual sessions:

# List all sessions
ccstat session

# Live monitoring
ccstat session --watch                      # Watch active sessions
ccstat session --watch --interval 5         # Refresh every 5 seconds

# JSON output with full details
ccstat session --json

# Filter by date range
ccstat session --since 2024-01-01 --until 2024-01-31

# Filter by project
ccstat session --project my-project

# Timezone configuration
ccstat session --timezone "Europe/London"   # Use specific timezone
ccstat session --utc                        # Force UTC timezone

# Model display options
ccstat session --full-model-names           # Show full model names

# Different cost calculation modes
ccstat session --mode calculate   # Always calculate from tokens
ccstat session --mode display     # Use pre-calculated costs only

Billing Blocks

Track 5-hour billing blocks:

# Show all blocks
ccstat blocks

# Live monitoring
ccstat blocks --watch                       # Watch billing blocks update
ccstat blocks --watch --active              # Visual live monitor with progress bars (recommended)
ccstat blocks --watch --interval 10         # Custom refresh interval
ccstat blocks --watch --active --max-cost 100 # Set custom $100 limit for progress calculations

# Only active blocks
ccstat blocks --active

# Recent blocks (last 24h)
ccstat blocks --recent

# JSON output
ccstat blocks --json

# Filter by project
ccstat blocks --project my-project

# Filter by date range
ccstat blocks --since 2025-08-01
ccstat blocks --since 2025-08-01 --until 2025-08-15

# Set token limit for warnings
ccstat blocks --token-limit "80%"

# Custom billing block duration (default: 5 hours)
ccstat blocks --session-duration 3.0

# Timezone configuration
ccstat blocks --timezone "America/New_York"  # Use specific timezone
ccstat blocks --utc                          # Force UTC timezone

# Model display options
ccstat blocks --full-model-names            # Show full model names

Live Billing Block Monitor

The --watch --active combination provides a rich visual monitoring interface for active billing blocks:

ccstat blocks --watch --active

This displays a real-time ASCII art dashboard with:

• TIME Progress Bar: Shows how much of the current 5-hour billing block has elapsed

  • Visual progress bar with percentage completion
  • Start time, elapsed time, and time remaining until block ends

• USAGE Progress Bar: Tracks current cost and token consumption

  • Real-time cost tracking against monthly limit
  • Burn rate indicator (NORMAL/ELEVATED) based on usage patterns
  • Total tokens consumed in the current block

• PROJECTION Progress Bar: Estimates final cost for the billing block

  • Status indicator (WITHIN LIMITS/APPROACHING LIMIT/OVER LIMIT)