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.11+

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

pkg.pr.new preview

bunx -p https://pkg.pr.new/ryoppippi/ccusage@<pr-number> ccusage --offline

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

Runtime

bunx ccusage is recommended for everyday use. The npm package installs a small JavaScript launcher and the matching native binary package for your platform. Package runners such as bunx cache the downloaded package, so repeated runs reuse the cached native binary; the first run can still include network fetch time.

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