ccstats

ccstats is a fast CLI for token and cost usage analytics for Claude Code, OpenAI Codex, Cursor, and Grok 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)
• Grok support (~/.grok/sessions/)
• Daily/weekly/monthly/project/session views
• Top-N leaderboard ranking models or projects by cost share
• Optional model-level token and cost breakdown
• Reusable Rust SDK for embedding local usage and cost summaries in other apps

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.63 sh

Manual download

Download prebuilt archives and SHA-256 checksums 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

Quick Start (Grok)

Grok support reads local session summary.json, signals.json, and fallback updates.jsonl metadata under ~/.grok/sessions/. These files expose local context-token snapshots, not precise provider input/output billable usage or Grok account quota usage, so ccstats reports Grok context tokens as input tokens.

# Install
brew install majiayu000/tap/ccstats

# Today's local context-token trend
ccstats grok today

# Daily local context-token trend
ccstats grok

# Same source via alias
ccstats daily --source gx

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_with_cli_config};

let summary = summarize_cost_with_cli_config(SummaryOptions {
    source: UsageSource::Codex,
    range: UsageRange::Today,
    ..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. Use summarize_cost_with_cli_config when SDK output should follow the same persisted CLI defaults for timezone, offline pricing, strict pricing, and currency. Use summarize_cost when the caller wants fully explicit options. 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

# Top-N leaderboard (ranks by cost, falls back to tokens when costs unknown)
ccstats top                          # top 10 models by cost
ccstats top --dim project --limit 5  # top 5 projects

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

Grok

# Today's Grok local context-token trend
ccstats grok today

# Daily Grok local context-token breakdown
ccstats grok

# Weekly Grok local context-token summary
ccstats grok weekly

# By session
ccstats grok session

# By project
ccstats grok project

# Grok alias
ccstats daily --source gx

By default, ccstats checks Grok session files under:

• ~/.grok/sessions/**/summary.json
• ~/.grok/sessions/**/signals.json
• ~/.grok/sessions/**/updates.jsonl when signals.json is missing

You can override the Grok home directory with GROK_HOME:

GROK_HOME="/path/to/.grok" ccstats grok

Current limitations:

• Grok local session files expose context token usage, not exact provider input/output usage.
• These local context-token totals may not match Grok account, quota, or 5-hour usage UI totals when those views use server-side accounting.
• ccstats reports Grok context tokens as input tokens and leaves output, cache creation, cache read, and reasoning token fields at zero.
• Grok 5-hour billing blocks are not supported.

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

# Grok source and alias
ccstats daily --source grok
ccstats daily --source gx

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