Claude Usage Tracker: Complete Session Analytics for Claude Code Across Your Entire Machine

If you use Claude Code extensively, you have probably wondered: how much am I actually using it? The default ccusage command only reads from a single stats file, missing project-specific sessions and cache data scattered across your filesystem. Claude Usage Tracker is a Python tool that scans every location where Claude Code stores data — the main stats file, project-specific directories, cache directories, session history, and todo files — to give you a complete picture of your Claude Code usage with detailed breakdowns by model, project, and day.

The Problem

Claude Code stores usage data across multiple locations on your machine. The built-in ccusage command reads only from ~/.claude/stats-cache.json, which is the main aggregated statistics file. But Claude Code also creates .claude directories in each project you work on, maintains a session history in ~/.claude/history.jsonl, stores MCP logs and session caches in ~/.cache/claude-cli-nodejs/, and tracks active sessions through todo files in ~/.claude/todos/.

The result is that the default usage report significantly underestimates your actual usage. If you work across many projects — and power users of Claude Code regularly work across dozens or even hundreds of projects — the gap between reported and actual usage can be substantial.

With 903 total sessions, 22,099 messages, and 1.7 billion tokens across 93 projects, the difference between partial and complete tracking is not a rounding error — it is a blind spot.

The Solution

Claude Usage Tracker is a zero-dependency Python script that systematically scans all known Claude Code data locations, aggregates the statistics, and produces both a console report and a JSON export. It requires only Python 3.7+ and a local Claude Code installation — no pip packages, no virtual environments, no configuration files.

Key Features

Comprehensive Data Collection

The tool scans five distinct data locations:

Rich Reporting

The console report includes:

• Overview — Total sessions, messages, tokens, and unique projects
• Model Usage Breakdown — Input tokens, output tokens, and totals per model (Sonnet, Opus, Haiku, etc.)
• Project Breakdown — Sessions per project with disk usage statistics
• Daily Activity Timeline — Your Claude Code usage plotted over time
• Summary Statistics — Aggregate metrics for quick overview

JSON Export

In addition to the console report, the tool writes a structured JSON file to ~/.claude/claude-usage-complete.json. This enables further analysis with other tools, visualization in Jupyter notebooks, or integration with dashboards.

Zero Dependencies

The entire tool is a single Python file using only the standard library. No external packages are required, making installation trivial and ensuring it works on any system with Python 3.7+.

Technology Stack

Architecture

The tool follows a straightforward scan-aggregate-report architecture. On startup, it initializes paths based on the user’s home directory:

self.home = Path.home()
self.main_claude_dir = self.home / ".claude"
self.cache_dir = self.home / ".cache" / "claude-cli-nodejs"
self.projects_dir = Path("/home/projects")  # Configurable

The Scanner phase walks the filesystem to discover all data sources. It reads the main stats cache for aggregate token counts, parses the JSONL history file for session entries, counts todo files as session indicators, traverses project directories to find .claude folders, and scans the cache directory for MCP logs and session data.

The Aggregator phase merges data from all sources, deduplicating sessions that appear in multiple locations. It computes per-model, per-project, and per-day breakdowns. Token counts are carefully accumulated to avoid double-counting.

The Reporter phase formats the aggregated data into a structured console report with sections for overview, model usage, project breakdown, daily activity, and summary statistics. Simultaneously, it writes the complete dataset as JSON for programmatic access.

Filesystem Scan
    |
    +-- ~/.claude/stats-cache.json    (aggregate stats)
    +-- ~/.claude/history.jsonl       (session timeline)
    +-- ~/.claude/todos/              (session indicators)
    +-- ~/projects/*/.claude/         (per-project data)
    +-- ~/.cache/claude-cli-nodejs/   (cache + MCP logs)
    |
    v
Aggregation Engine
    |
    +-- Deduplicate sessions
    +-- Compute per-model totals
    +-- Compute per-project totals
    +-- Build daily timeline
    |
    v
Dual Output
    +-- Console Report (formatted text)
    +-- JSON Export (~/.claude/claude-usage-complete.json)

Installation and Usage

Installation is minimal:

# Clone and make executable
git clone https://github.com/red777777/claude-usage-tracker.git
cd claude-usage-tracker
chmod +x claude-usage-tracker.py
./install.sh  # Creates symlink in ~/.claude/

# Run from anywhere
python3 ~/.claude/complete-usage-tracker.py
# Or via the installed alias
ccusage-complete

Example Output

Here is what the report looks like for a power user:

OVERVIEW
--------------------------------------------------------------------------------
Total Sessions:        903
Total Messages:        22,099
Total Tokens:          1,733,962,135
Unique Projects:       93
First Session:         2025-11-07T09:13:43.926Z

MODEL USAGE
--------------------------------------------------------------------------------
claude-sonnet-4-5-20250929:
  Input tokens:        296,667
  Output tokens:       2,485,378
  Total:               807,765,314

The numbers tell a story: nearly 2 billion tokens consumed across 903 sessions and 93 projects. This is the kind of insight that the default ccusage command simply cannot provide because it only sees a fraction of the data.

Privacy

Claude Usage Tracker only reads local files on your machine. No data is sent externally. The generated JSON export contains usage statistics (token counts, session counts, project names) but no conversation content. Your actual interactions with Claude Code remain private.

Looking Ahead

For anyone who relies on Claude Code as a daily development tool, understanding usage patterns is valuable — whether for budgeting API costs, tracking productivity, or simply satisfying curiosity about how much you interact with your AI assistant. Claude Usage Tracker fills a gap that the built-in tooling leaves open, and it does so with the simplicity of a single Python file and zero dependencies.