ccstats

ccstats is a fast CLI for token and cost usage analytics for Claude Code and OpenAI Codex logs.

Search keywords: claude code usage stats, codex usage stats, token usage cli, ai token cost tracker.

Highlights

• Fast local analysis of usage JSONL logs
• Claude Code support (~/.claude/projects/)
• OpenAI Codex support (~/.codex/sessions/)
• Daily/weekly/monthly/project/session views
• Optional model-level token and cost breakdown

Installation

Homebrew (macOS/Linux)

brew install majiayu000/tap/ccstats

Cargo binstall (prebuilt binary)

cargo binstall ccstats

Cargo install (from source)

cargo install ccstats

Shell script

curl -fsSL https://raw.githubusercontent.com/majiayu000/ccstats/main/install.sh | sh

Manual download

Download from GitHub Releases.

Quick Start (Codex)

# Install
brew install majiayu000/tap/ccstats

# Today
ccstats codex today

# Daily trend
ccstats codex daily

# Same result via unified source flag
ccstats daily --source codex

Usage

Claude Code

# Today's usage
ccstats today

# Daily breakdown
ccstats daily

# Weekly summary
ccstats weekly

# Monthly summary
ccstats monthly

# By project
ccstats project

# By session
ccstats session

# 5-hour billing blocks
ccstats blocks

# With model breakdown
ccstats today -b

# JSON output
ccstats today -j

# Debug mode (timing info)
ccstats today --debug

OpenAI Codex

# Codex subcommand mode
ccstats codex daily

# Or use unified source flag
ccstats daily --source codex

# Today's Codex usage
ccstats codex today

# Daily Codex breakdown
ccstats codex daily

# Weekly Codex summary
ccstats codex weekly

# By session
ccstats codex session

# With model breakdown
ccstats codex today -b

Common Options

# Bucket by timezone
ccstats daily --timezone UTC

# Locale-aware number formatting
ccstats monthly --locale de

# Filter by date
ccstats daily --since 20260101 --until 20260131

# Select data source explicitly (supports aliases)
ccstats daily --source codex

# Offline mode (use cached pricing)
ccstats today -O

# Compact output
ccstats today -c

# Hide cost column
ccstats today --no-cost

Session CSV Columns

ccstats session --csv now includes:

• reasoning_tokens
• cache_creation_tokens
• cache_read_tokens

Parsing Warnings

When malformed JSONL records are encountered, ccstats reports them in stderr:

Warning: ignored <N> malformed records

Supported Data Sources

Architecture

See docs/ARCHITECTURE.md for:

• Adding new data sources
• Data flow and processing pipeline
• Caching mechanism
• Deduplication algorithm

License

MIT. See LICENSE.