gcusage

📊 AI coding agent usage tracker — analyze token usage and costs from local data.

Supports GitHub Copilot CLI and Claude Code. Inspired by ccusage (11.8k⭐). 100% offline, zero telemetry.

Features

• 📊 Daily/Monthly reports — token usage aggregated by date
• 💬 Session breakdown — per-session details with repo, model, tools
• 🤖 Model analysis — cost distribution across models with visual share bars
• 💰 Cost estimation — based on known model pricing
• 🔒 100% offline — reads only ~/.copilot/ and ~/.claude/ local data, never sends anything externally
• 📋 JSON export — --json flag for scripting and automation
• 🔀 Multi-provider — unified view across Copilot CLI and Claude Code

Quick Start

# Run directly — no install needed
npx gcusage

# Or install globally
npm i -g gcusage
gcusage

Usage

gcusage              # Daily report — all providers (default)
gcusage daily        # Daily token usage and costs
gcusage monthly      # Monthly aggregated report
gcusage session      # Per-session breakdown
gcusage models       # Per-model usage distribution

Options

-p, --provider <p>   # Data source: copilot, claude, or all (default: all)
--since YYYYMMDD     # Filter sessions since date
--until YYYYMMDD     # Filter sessions until date
--json               # Output as JSON

Examples

# All providers — last 7 days
gcusage --since 20260317

# Claude Code only
gcusage -p claude

# Copilot only — March 2026 as JSON
gcusage monthly -p copilot --since 20260301 --until 20260331 --json

# Session details for this week
gcusage session --since 20260320

Sample Output

📊 GitHub Copilot CLI — Daily Usage Report

┌────────────┬──────────┬───────────────┬────────────┬───────────┬────────┬──────────────────────┐
│ Date       │ Sessions │ Output Tokens │ Est. Input │ Est. Cost │  Tools │ Models               │
├────────────┼──────────┼───────────────┼────────────┼───────────┼────────┼──────────────────────┤
│ 2026-03-23 │       45 │        92,577 │     32,911 │     $7.31 │    299 │ claude-opus-4.6-1m   │
│ 2026-03-24 │       19 │       108,035 │     10,381 │     $8.26 │    367 │ claude-opus-4.6-1m   │
├────────────┼──────────┼───────────────┼────────────┼───────────┼────────┼──────────────────────┤
│ Total      │      701 │     1,105,358 │    460,275 │    $35.04 │ 14,053 │                      │
└────────────┴──────────┴───────────────┴────────────┴───────────┴────────┴──────────────────────┘

Data Sources

gcusage reads from local data only — no network requests, ever.

GitHub Copilot CLI (~/.copilot/)

File	Data
~/.copilot/session-state/<id>/events.jsonl	Token counts, tool calls, model info
~/.copilot/session-state/<id>/workspace.yaml	Session metadata (repo, branch, summary)
~/.copilot/config.json	Current model selection

Claude Code (~/.claude/)

File	Data
~/.claude/stats-cache.json	Daily activity, per-model tokens, aggregate usage
~/.claude/history.jsonl	Per-message history with session IDs, projects

Token Estimation

• Copilot output tokens: Direct from assistant.message.data.outputTokens
• Claude output tokens: From stats-cache.json daily model token aggregates
• Input tokens: Estimated from user message content (~4 chars/token)
• Cost: Calculated per-model using known pricing tables

Privacy

• ✅ 100% offline — never connects to any external service
• ✅ Read-only — only reads Copilot CLI and Claude Code local files
• ✅ No telemetry — zero analytics, zero tracking, zero data collection
• ✅ Open source — MIT license, audit the code yourself

Comparison

Tool	⭐	Copilot CLI	Offline	Language
gcusage	new	✅	✅ 100%	TypeScript
ccusage	11.8k	❌ Claude only	✅	TypeScript
tokscale	1.3k	❌	⚠️ leaderboard	Rust
splitrail	134	✅	⚠️ cloud upload	Rust
aidash	0	✅	✅	Rust

Development

git clone https://github.com/chongdihuang/gcusage
cd gcusage
npm install
npm run dev          # Run with tsx
npm run build        # Build with tsup
npm test             # Run tests

License

MIT © Chongdi Huang