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

Source	Directory	Features
Claude Code	`~/.claude/projects/`	Projects, Billing Blocks, Deduplication
OpenAI Codex	`~/.codex/sessions/`	Reasoning Tokens
All Sources	Multiple	Combined daily/weekly/monthly/today/statusline summaries
Cursor (experimental)	Cursor `User/globalStorage/state.vscdb`	Local SQLite `tokenCount` fields only
Grok	`~/.grok/sessions/`	Context-token session summaries, Projects

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.

Name		Name	Last commit message	Last commit date
Latest commit History 170 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
deny.toml		deny.toml
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ccstats

Highlights

Installation

Homebrew (macOS/Linux)

Cargo binstall (prebuilt binary)

Cargo install (from source)

Shell script

Manual download

Quick Start (Codex)

Quick Start (Cursor)

Quick Start (Grok)

Crate Documentation

Rust SDK

Usage

Claude Code

OpenAI Codex

Cursor (Experimental)

Grok

Common Options

Session CSV Columns

Parsing Warnings

Supported Data Sources

Architecture

License

About

Uh oh!

Releases 10

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ccstats

Highlights

Installation

Homebrew (macOS/Linux)

Cargo binstall (prebuilt binary)

Cargo install (from source)

Shell script

Manual download

Quick Start (Codex)

Quick Start (Cursor)

Quick Start (Grok)

Crate Documentation

Rust SDK

Usage

Claude Code

OpenAI Codex

Cursor (Experimental)

Grok

Common Options

Session CSV Columns

Parsing Warnings

Supported Data Sources

Architecture

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages