ccstats

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

Search keywords: claude code usage stats, codex usage stats, cursor 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/)
• Experimental Cursor support (Cursor/User/globalStorage/state.vscdb)
• 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

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/majiayu000/ccstats/main/install.sh | VERSION=v0.2.61 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

Quick Start (Cursor)

Cursor support is experimental because Cursor's local database schema is not a public API. ccstats reads local SQLite tokenCount fields only and does not estimate missing usage.

# Install
brew install majiayu000/tap/ccstats

# Today
ccstats today --source cursor

# Daily trend
ccstats daily --source cursor

# Same source via alias
ccstats daily --source cur

Crate Documentation

• docs.rs: https://docs.rs/ccstats/latest/ccstats/
• crates.io: https://crates.io/crates/ccstats
• The crate-level Rustdoc in src/lib.rs explains the SDK entry points and CLI runtime.

Rust SDK

ccstats can be used as a Rust library when another app needs structured local usage and cost data without spawning the CLI.

use ccstats::{SummaryOptions, UsageRange, UsageSource, summarize_cost};

let summary = summarize_cost(SummaryOptions {
    source: UsageSource::Codex,
    range: UsageRange::Today,
    timezone: Some("UTC".to_string()),
    offline: true,
    ..SummaryOptions::default()
})?;

println!("today: ${:.2}", summary.cost_usd.unwrap_or(0.0));

The SDK uses the same source registry, parsers, aggregation logic, pricing cache, and fallback pricing as the CLI. Returned summaries include total tokens, cache read/create tokens, reasoning tokens, per-model breakdowns, cost_usd, and an optional converted cost when SummaryOptions::currency is set.

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

Cursor (Experimental)

Cursor uses the unified source flag rather than a dedicated subcommand.

# Today's Cursor usage
ccstats today --source cursor

# Daily Cursor breakdown
ccstats daily --source cursor

# Weekly Cursor summary
ccstats weekly --source cursor

# By session/conversation
ccstats session --source cursor

# Cursor alias
ccstats daily --source cur

By default, ccstats checks these local Cursor databases:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
• Linux: ~/.config/Cursor/User/globalStorage/state.vscdb
• workspaceStorage/*/state.vscdb under the same Cursor user directory

You can override the Cursor user directory with CURSOR_HOME:

CURSOR_HOME="/path/to/Cursor/User" ccstats daily --source cursor

Current limitations:

• Only explicit tokenCount/usage fields are counted.
• Project aggregation and 5-hour billing blocks are not supported for Cursor.
• Cache creation, cache read, and reasoning token fields are reported as zero unless Cursor exposes them directly in a supported local record.

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

# Monthly budget forecast (uses --until as the as-of date when present)
ccstats monthly --monthly-budget 25 --until 20260415

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

# Combine all supported data sources
ccstats monthly --source all

# Experimental Cursor source (reads local SQLite tokenCount fields)
ccstats daily --source cursor

# Cursor alias
ccstats daily --source cur

# 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
• Architecture and module boundaries

See docs/algorithm/authoritative-token-accounting.md for:

• Token accounting rules
• Source-specific normalization
• Deduplication semantics

License

MIT. See LICENSE.