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, or Node.js 22+

Quick Start

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

bunx (Recommended)

bunx ccusage

npx

npx ccusage@latest

pnpm

pnpm dlx ccusage

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

Runtime

bunx ccusage is recommended for everyday use. ccusage can run on Node.js 22+, and because the published CLI shebang targets Node.js, package runners can start ccusage under Node.js even when launched through bunx. When ccusage finds bun in PATH, it automatically re-runs the bundled entrypoint with Bun for better warm runtime performance. Set CCUSAGE_BUN_AUTO_RUN=0 to force Node.js.

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

ccusage claude daily
ccusage codex daily
ccusage opencode weekly
ccusage amp session
ccusage pi monthly

Your First Report

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

╭──────────────────────────────────────────╮
│                                          │
│  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

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

Focus on One Source

ccusage codex daily
ccusage claude monthly

Use Source-Specific Options

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

Analyze Sessions

ccusage session

Export for Analysis

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:-~/.local/share/opencode}
   • Amp: ${AMP_DATA_DIR:-~/.local/share/amp}
   • pi-agent: ${PI_AGENT_DIR:-~/.pi/agent/sessions}

Custom Data Directory

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

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 PI_AGENT_DIR="/path/to/pi/sessions"

Each source-specific path variable can also contain comma-separated directories:

export CODEX_HOME="/path/to/codex,/archive/codex"
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"

Getting Help

• Use ccusage --help for command options
• Visit our GitHub repository for issues
• Use JSON Output for programmatic usage