ccusage

Getting Started ​

Welcome to ccusage! This guide will help you get up and running with analyzing your coding (agent) CLI usage data.

Prerequisites ​

  • At least one supported coding CLI installed and used
  • Bun 1.3+ recommended for direct execution

Quick Start ​

The fastest way to try ccusage is to run it directly without installation:

bash
bunx ccusage
bash
nix run github:ccusage/ccusage -- daily
bash
npx ccusage@latest
bash
pnpm dlx ccusage
bash
bunx -p https://pkg.pr.new/ccusage/ccusage@<pr-number> ccusage --offline

This will show your daily usage report for all detected supported coding CLIs by default.

Runtime

bunx caches the downloaded package, so repeated runs are faster after the first launch.

Use a data source namespace when you want the same report focused on one source:

bash
ccusage claude daily
ccusage codex daily
ccusage opencode weekly
ccusage amp session
ccusage pi monthly
ccusage kilo daily
ccusage kimi daily
ccusage qwen daily

Your First Report ​

When you run ccusage for the first time, you'll see a table showing detected coding CLI usage by date:

text
╭──────────────────────────────────────────╮
│                                          │
│  Coding (Agent) CLI Usage Report - Daily │
│                                          │
╰──────────────────────────────────────────╯

┌────────────┬────────┬────────────────┬────────┬────────┬────────────┐
│ Date       │ Agent  │ Models         │ Input  │ Output │ Cost (USD) │
├────────────┼────────┼────────────────┼────────┼────────┼────────────┤
│ 2026-05-16 │ Claude │ • sonnet-4-5   │  1,234 │ 15,678 │     $12.34 │
│ 2026-05-16 │ Codex  │ • gpt-5.5      │    890 │ 12,345 │     $18.92 │
└────────────┴────────┴────────────────┴────────┴────────┴────────────┘

Understanding the Output ​

Columns Explained ​

  • Date: The date when an agent was used
  • Agent: The coding CLI that generated the usage
  • Models: Which models were used
  • Input: Number of input tokens sent to the agent/model
  • Output: Number of output tokens received from the agent/model
  • Cost (USD): Estimated cost based on model pricing

Cache Tokens ​

If you have a wide terminal, you'll also see cache token columns:

  • Cache Create: Tokens used to create cache entries
  • Cache Read: Tokens read from cache (typically cheaper)

Next Steps ​

Now that you have your first unified view, explore these features:

  1. All Sources (Default) - Understand the default unified behavior
  2. Weekly Usage - Track usage patterns by week
  3. Monthly Usage - See usage aggregated by month
  4. Session Usage - Analyze individual conversations
  5. Configuration - Customize ccusage behavior
  6. Claude Code - Claude Code-specific setup and features

Common Use Cases ​

Monitor Daily Usage ​

bash
ccusage daily --since 2026-05-01 --until 2026-05-16

Focus on One Source ​

bash
ccusage codex daily
ccusage claude monthly
ccusage zcode daily

Use Source-Specific Options ​

bash
ccusage claude daily --mode display
ccusage codex daily --speed fast
ccusage opencode weekly

Analyze Sessions ​

bash
ccusage session

Export for Analysis ​

bash
ccusage monthly --json > usage-data.json

Claude Code Features ​

See Claude Code for Claude-specific features such as blocks and statusline integration.

Colors ​

ccusage automatically colors the output based on the terminal's capabilities. If you want to disable colors, you can use the --no-color flag. Or you can use the --color flag to force colors on.

Automatic Table Adjustment ​

ccusage automatically adjusts its table layout based on terminal width:

  • Wide terminals (≥100 characters): Full table with all columns including cache metrics, model names, and detailed breakdowns
  • Narrow terminals (<100 characters): Compact view with essential columns only (Date, Models, Input, Output, Cost)

The layout adjusts automatically based on your terminal width - no configuration needed. If you're in compact mode and want to see the full data, simply expand your terminal window.

Troubleshooting ​

No Data Found ​

If ccusage shows no data, check:

  1. A supported coding CLI is installed and used - ccusage reads from local usage files
  2. Data directory exists - Common locations:
    • Claude Code: ~/.config/claude/projects/ or ~/.claude/projects/
    • Codex: ${CODEX_HOME:-~/.codex}
    • OpenCode: ${OPENCODE_DATA_DIR-${XDG_DATA_HOME:-$HOME/.local/share}/opencode} (the fallback applies only when OPENCODE_DATA_DIR is unset)
    • Amp: ${AMP_DATA_DIR:-~/.local/share/amp}
    • Droid: ${DROID_SESSIONS_DIR:-~/.factory/sessions}
    • Codebuff: ${CODEBUFF_DATA_DIR:-~/.config/manicode}
    • Hermes Agent: ${HERMES_HOME:-~/.hermes}/state.db
    • pi-agent: ${PI_AGENT_DIR:-~/.pi/agent/sessions}
    • Goose: standard Goose data roots or GOOSE_PATH_ROOT
    • Kilo: ${KILO_DATA_DIR:-~/.local/share/kilo}
    • Kimi: ${KIMI_DATA_DIR:-~/.kimi} (also scans ~/.kimi-code)
    • OpenClaw: ${OPENCLAW_DIR:-~/.openclaw} (also scans ~/.clawdbot, ~/.moltbot, ~/.moldbot)
    • Qwen: ${QWEN_DATA_DIR:-~/.qwen}
    • GitHub Copilot CLI: ${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl, ${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl, or the single file specified by COPILOT_OTEL_FILE_EXPORTER_PATH
    • Antigravity: ${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity*} or ~/.config/antigravity
    • Grok Build CLI: ${GROK_HOME:-~/.grok}
    • ZCode: ${ZCODE_HOME:-~/.zcode}/cli/db/db.sqlite

Custom Data Directory ​

If your agent data is in a custom location, set the matching environment variable:

bash
export CLAUDE_CONFIG_DIR="/path/to/your/claude/data"
export CODEX_HOME="/path/to/codex"
export OPENCODE_DATA_DIR="/path/to/opencode"
export AMP_DATA_DIR="/path/to/amp"
export DROID_SESSIONS_DIR="/path/to/factory/sessions"
export CODEBUFF_DATA_DIR="/path/to/manicode"
export HERMES_HOME="/path/to/hermes"
export PI_AGENT_DIR="/path/to/pi/sessions"
export GOOSE_PATH_ROOT="/path/to/goose"
export OPENCLAW_DIR="/path/to/openclaw"
export KILO_DATA_DIR="/path/to/kilo"
export KIMI_DATA_DIR="/path/to/kimi"
export QWEN_DATA_DIR="/path/to/qwen"
export COPILOT_HOME="/path/to/copilot"
export ANTIGRAVITY_DATA_DIR="/path/to/antigravity"
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
export GROK_HOME="/path/to/grok-home"
export ZCODE_HOME="/path/to/zcode-home"

Directory variables can contain comma-separated directories, except COPILOT_HOME and GROK_HOME, which take a single root. COPILOT_OTEL_FILE_EXPORTER_PATH points to one JSONL file, and ZCODE_HOME supports multiple roots and deduplicates them:

bash
export CODEX_HOME="/path/to/codex,/archive/codex,/path/to/codex-exec-jsonl"
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
export DROID_SESSIONS_DIR="/path/to/factory/sessions,/archive/factory/sessions"
export CODEBUFF_DATA_DIR="/path/to/manicode,/archive/manicode"
export HERMES_HOME="/path/to/hermes,/archive/hermes"
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
export GOOSE_PATH_ROOT="/path/to/goose,/archive/goose"
export OPENCLAW_DIR="/path/to/openclaw,/archive/openclaw"
export KILO_DATA_DIR="/path/to/kilo,/archive/kilo"
export KIMI_DATA_DIR="/path/to/kimi,/archive/kimi"
export QWEN_DATA_DIR="/path/to/qwen,/archive/qwen"
export ANTIGRAVITY_DATA_DIR="/path/to/antigravity,/archive/antigravity"
export ZCODE_HOME="/path/to/zcode,/archive/zcode"

Getting Help ​

Released under the MIT License.

Copyright © 2025 ryoppippi