---
url: /guide.md
---
# Introduction

![ccusage daily report showing token usage and costs by date](/screenshot.png)

**ccusage** is a local CLI for understanding coding (agent) CLI token usage and estimated costs across Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode.

The original **“cc”** came from **C**laude **C**ode usage and now also fits **C**odex **C**LI usage. As OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, Gemini CLI, Antigravity, Grok Build CLI, ZCode, and other coding (agent) CLIs became part of the same workflow, ccusage expanded into a general name for local coding CLI usage analysis.

## The Problem

Modern coding (agent) CLI usage is split across several local data formats. That makes basic questions hard to answer:

* How much am I actually using each coding CLI?
* Which conversations are the most expensive?
* What would I be paying on a pay-per-use plan?
* Which projects, sessions, or weeks are driving usage?

## The Solution

ccusage reads the local usage files that coding CLIs already generate and provides:

* **All Sources by Default** - Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode in one CLI
* **Usage Views** - Daily, weekly, monthly, and session-based breakdowns
* **Cost Analysis** - Estimated costs based on token usage and model pricing
* **Focused Data Source Views** - Start with all detected sources, then narrow the same usage views to one source when needed
* **Data Source Pages** - Source-specific setup and extra features live with each supported data source
* **Multiple Formats** - Beautiful tables or JSON for further analysis

## How It Works

1. **Coding CLIs generate local usage files** containing usage data
2. **ccusage reads these files** from your local machine
3. **Analyzes and aggregates** the data by date, session, or time blocks
4. **Calculates estimated costs** using model pricing information
5. **Presents results** in beautiful tables or JSON format

## Key Features

### 🚀 Direct Execution

You can run ccusage without a global install using `bunx ccusage` (recommended), `pnpm dlx ccusage`, or `npx ccusage@latest`.

### 📊 Usage Views

* **All Sources (Default)** - Aggregates every detected supported source
* **Daily Usage** - Usage aggregated by calendar date
* **Weekly Usage** - Usage aggregated by week with configurable start day
* **Monthly Usage** - Monthly summaries with trends
* **Session Usage** - Per-conversation analysis

### 💰 Cost Analysis

* Estimated costs based on token counts and model pricing
* Support for different cost calculation modes
* Model-specific pricing across supported providers
* Cache token cost calculation

### Data Source Pages

Each data source page covers the details that only apply to that source, including custom directories, pricing notes, and source-specific commands.

### 🔧 Flexible Configuration

* **JSON Configuration Files** - Set defaults for all commands or customize per-command
* **IDE Support** - JSON Schema for autocomplete and validation
* **Priority-based Settings** - CLI args > local config > user config > defaults
* **Environment Variables** - Traditional configuration options
* **Custom Date Filtering** - Flexible time range selection and sorting
* **Offline Mode** - Cached pricing data for air-gapped environments

## Data Sources

ccusage reads from local coding CLI data directories:

| Agent          | ID            | Default data location                                                                                     |
| -------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| Claude Code    | `claude`      | `~/.config/claude/projects/`, `~/.claude/`                                                                |
| Codex          | `codex`       | `${CODEX_HOME:-~/.codex}`                                                                                 |
| OpenCode       | `opencode`    | `${OPENCODE_DATA_DIR-${XDG_DATA_HOME:-$HOME/.local/share}/opencode}`                                      |
| Amp            | `amp`         | `${AMP_DATA_DIR:-~/.local/share/amp}`                                                                     |
| Droid          | `droid`       | `${DROID_SESSIONS_DIR:-~/.factory/sessions}`                                                              |
| Codebuff       | `codebuff`    | `${CODEBUFF_DATA_DIR:-~/.config/manicode}`                                                                |
| Hermes Agent   | `hermes`      | `${HERMES_HOME:-~/.hermes}/state.db`                                                                      |
| pi-agent       | `pi`          | `${PI_AGENT_DIR:-~/.pi/agent/sessions}`                                                                   |
| Goose          | `goose`       | Standard Goose data roots or `GOOSE_PATH_ROOT`                                                            |
| OpenClaw       | `openclaw`    | `${OPENCLAW_DIR:-~/.openclaw}`                                                                            |
| Kilo           | `kilo`        | `${KILO_DATA_DIR:-~/.local/share/kilo}`                                                                   |
| Kimi           | `kimi`        | `${KIMI_DATA_DIR:-~/.kimi}` (also `~/.kimi-code`)                                                         |
| Qwen           | `qwen`        | `${QWEN_DATA_DIR:-~/.qwen}`                                                                               |
| Copilot CLI    | `copilot`     | `${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl`, `${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl` |
| Gemini CLI     | `gemini`      | `${GEMINI_DATA_DIR:-~/.gemini/tmp}`                                                                       |
| Antigravity    | `antigravity` | `${ANTIGRAVITY_DATA_DIR:-~/.gemini/antigravity*}` or `~/.config/antigravity`                              |
| Grok Build CLI | `grok`        | `${GROK_HOME:-~/.grok}`                                                                                   |
| ZCode          | `zcode`       | `${ZCODE_HOME:-~/.zcode}`                                                                                 |

For OpenCode, `${XDG_DATA_HOME:-$HOME/.local/share}/opencode` is the default-path fallback. When set, `OPENCODE_DATA_DIR` overrides that path; an explicitly empty value disables fallback discovery.

The tool automatically detects available data and aggregates all supported coding CLIs by default.
Source-specific environment variables that support multiple roots can contain comma-separated directories, which lets unified reports combine current profiles and archives.

Some coding agents have been investigated but are not supported because their local files do not contain reliable token usage. See [Source Support Q\&A](/guide/source-support-qa) for the current notes on legacy Grok CLI SQLite data and Devin CLI.

## Report Shape

Run ccusage without a source name to aggregate all detected sources:

```bash
ccusage daily
ccusage weekly
ccusage monthly
ccusage session
```

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

```bash
ccusage claude daily
ccusage codex daily --speed fast
ccusage opencode weekly
ccusage amp session
ccusage droid daily
ccusage codebuff daily
ccusage hermes daily
ccusage pi monthly
ccusage goose daily
ccusage openclaw daily
ccusage kilo daily
ccusage kimi daily
ccusage qwen daily
ccusage copilot daily
ccusage gemini daily
ccusage antigravity daily
ccusage grok daily
ccusage zcode daily
```

Use `ccusage <source> <report>` only when you want to narrow a report to one source.

For Claude Code-specific setup and features, start from the [Claude Code data source](/guide/claude/) page.

## Privacy & Security

* **100% Local** - All analysis happens on your machine
* **No Data Transmission** - Your usage data never leaves your computer
* **Read-Only** - ccusage only reads files, never modifies them
* **Open Source** - Full transparency in how your data is processed

## Limitations

::: warning Important Limitations

* **Local Files Only** - Only analyzes data from your current machine
* **Language Model Tokens** - API calls for tools like Web Search are not included
* **Estimate Accuracy** - Costs are estimates and may not reflect actual billing
  :::

## Acknowledgments

Thanks to [@milliondev](https://note.com/milliondev) for the [original concept and approach](https://note.com/milliondev/n/n1d018da2d769) to Claude Code usage analysis.

## Getting Started

Ready to analyze your coding (agent) CLI usage? Start with the [Getting Started Guide](/guide/getting-started).

---

---
url: /guide/getting-started.md
---
# 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:

::: code-group

```bash [bunx (Recommended)]
bunx ccusage
```

```bash [Nix]
nix run github:ccusage/ccusage -- daily
```

```bash [npx]
npx ccusage@latest
```

```bash [pnpm]
pnpm dlx ccusage
```

```bash [pkg.pr.new preview]
bunx -p https://pkg.pr.new/ccusage@<pr-number-or-commit-sha> ccusage --offline
```

:::

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

::: tip Runtime
[bunx](https://bun.com/docs/pm/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)](/guide/all-reports)** - Understand the default unified behavior
2. **[Weekly Usage](/guide/weekly-reports)** - Track usage patterns by week
3. **[Monthly Usage](/guide/monthly-reports)** - See usage aggregated by month
4. **[Session Usage](/guide/session-reports)** - Analyze individual conversations
5. **[Configuration](/guide/configuration)** - Customize ccusage behavior
6. **[Claude Code](/guide/claude/)** - 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](/guide/claude/) 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

* Use `ccusage --help` for command options
* Visit our [GitHub repository](https://github.com/ccusage/ccusage) for issues
* Use [JSON Output](/guide/json-output) for programmatic usage

---

---
url: /guide/installation.md
---
# Installation

ccusage can be installed and used in several ways depending on your preferences and use case.

## Why Direct Execution Works Well

You do not need to install ccusage globally before trying it. Direct package runners work well for ad hoc usage:

* ✅ No global package to manage
* ✅ Easy access to the latest published version
* ✅ Cached package downloads after the first run

## Quick Start (Recommended)

The fastest way to use ccusage is to run it directly:

::: code-group

```bash [bunx (Recommended)]
bunx ccusage
```

```bash [pnpm]
pnpm dlx ccusage
```

```bash [npx]
npx ccusage@latest
```

```bash [pkg.pr.new preview]
bunx -p https://pkg.pr.new/ccusage@<pr-number-or-commit-sha> ccusage --offline
```

:::

::: tip Speed Recommendation
We recommend [bunx](https://bun.com/docs/pm/bunx) for everyday use. It caches the downloaded package, so repeated runs are faster after the first launch.
:::

### Performance Comparison

Here's why runtime choice matters:

| Runtime  | First Run | Subsequent Runs | Notes                        |
| -------- | --------- | --------------- | ---------------------------- |
| bunx     | Fast      | **Instant**     | Recommended for everyday use |
| pnpm dlx | Fast      | Fast            | Good alternative             |
| npx      | Slow      | Moderate        | Widely available             |

## Global Installation (Optional)

You can install ccusage globally if you prefer a persistent command:

::: code-group

```bash [npm]
npm install -g ccusage
```

```bash [bun]
bun install -g ccusage
```

```bash [yarn]
yarn global add ccusage
```

```bash [pnpm]
pnpm add -g ccusage
```

:::

After global installation, run commands directly:

```bash
ccusage daily
ccusage monthly --breakdown
ccusage blocks --live
```

## Development Installation

For development or contributing to ccusage:

```bash
# Clone the repository
git clone https://github.com/ccusage/ccusage.git
cd ccusage

# Allow direnv to load the Nix dev shell
direnv allow
```

The Nix dev shell provides the pinned `pnpm`, Rust toolchain, GitHub CLI, git hooks, package tooling, and project utilities. Run project tasks with `just`:

```bash
# Format the tree
just fmt

# Run tests
just test

# Run static checks
just check

# Build distribution
just build
```

You can also run the package directly from source:

```bash
pnpm --filter ccusage start daily
pnpm --filter ccusage start monthly --json
```

## Runtime Requirements

### Node.js

* Needed when using Node-based package runners or npm-style global installs
* Use Bun for direct execution when available

### Bun

* **Minimum**: Bun 1.3+
* **Recommended**: Latest stable release
* Recommended for `bunx ccusage` and for the fastest warm startup

## Verification

After installation, verify ccusage is working:

```bash
# Check version
ccusage --version

# Run help command
ccusage --help

# Test with daily report
ccusage daily
```

## Updating

### Direct Execution (npx/bunx)

Always gets the latest version automatically.

### Global Installation

```bash
# Update with npm
npm update -g ccusage

# Update with bun
bun update -g ccusage
```

### Check Current Version

```bash
ccusage --version
```

## Uninstalling

### Global Installation

::: code-group

```bash [npm]
npm uninstall -g ccusage
```

```bash [bun]
bun remove -g ccusage
```

```bash [yarn]
yarn global remove ccusage
```

```bash [pnpm]
pnpm remove -g ccusage
```

:::

### Development Installation

```bash
# Remove cloned repository
rm -rf ccusage/
```

## Troubleshooting Installation

### Permission Errors

If you get permission errors during global installation:

::: code-group

```bash [npm]
# Use npx instead of global install
npx ccusage@latest

# Or configure npm to use a different directory
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

```bash [Node Version Managers]
# Use nvm
nvm install 22
npm install -g ccusage

# Or use fnm
fnm install 22
npm install -g ccusage
```

:::

### Network Issues

If installation fails due to network issues:

```bash
# Try with different registry
npm install -g ccusage --registry https://registry.npmjs.org

# Or use bunx for offline-capable runs
bunx ccusage
```

### Version Conflicts

If you have multiple versions installed:

```bash
# Check which version is being used
which ccusage
ccusage --version

# Uninstall and reinstall
npm uninstall -g ccusage
npm install -g ccusage@latest
```

## Next Steps

After installation, check out:

* [Getting Started Guide](/guide/getting-started) - Your first usage report
* [Configuration](/guide/configuration) - Customize ccusage behavior
* [Daily Usage](/guide/daily-reports) - Understand daily usage patterns

---

---
url: /guide/all-reports.md
---
# All Sources (Default)

![ccusage daily report showing unified token usage and costs across sources](/screenshot.png)

ccusage aggregates every detected supported data source by default. You do not need a special `all` command or flag for the common case.

## Basic Usage

```bash
# Daily usage across every detected source
ccusage
ccusage daily

# Other unified views
ccusage weekly
ccusage monthly
ccusage session
```

The `--all` flag is accepted for compatibility, but it is optional because unified views are already the default.

```bash
ccusage daily --all
```

For automation, unified JSON reports can emit several report sections from one load:

```bash
ccusage daily --sections daily,monthly,session --json
ccusage daily --by-agent --json
```

`--sections` accepts `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included, and table output prints each requested section as a separate table. `--by-agent` adds an `agents` array to daily, weekly, and monthly JSON rows; session rows are already source-specific.

## How Unified Views Work

ccusage detects local usage files from Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode. The same daily, weekly, monthly, and session views can run in two modes:

| Mode    | Command example        | What it shows                           |
| ------- | ---------------------- | --------------------------------------- |
| Unified | `ccusage daily`        | Every detected supported source         |
| Focused | `ccusage codex daily`  | One source using the same report shape  |
| Focused | `ccusage claude daily` | One source with source-specific options |

Unified tables include an **Agent** column so you can compare sources in one view. Focused views remove that comparison layer and show the selected source in more detail where applicable.

## Supported Sources

| Source         | Namespace     | Example focused view        |
| -------------- | ------------- | --------------------------- |
| Claude Code    | `claude`      | `ccusage claude daily`      |
| Codex          | `codex`       | `ccusage codex daily`       |
| OpenCode       | `opencode`    | `ccusage opencode weekly`   |
| Amp            | `amp`         | `ccusage amp session`       |
| Droid          | `droid`       | `ccusage droid daily`       |
| Codebuff       | `codebuff`    | `ccusage codebuff daily`    |
| Hermes Agent   | `hermes`      | `ccusage hermes daily`      |
| pi-agent       | `pi`          | `ccusage pi monthly`        |
| Goose          | `goose`       | `ccusage goose daily`       |
| OpenClaw       | `openclaw`    | `ccusage openclaw daily`    |
| Kilo           | `kilo`        | `ccusage kilo daily`        |
| Kimi           | `kimi`        | `ccusage kimi daily`        |
| Qwen           | `qwen`        | `ccusage qwen daily`        |
| Copilot CLI    | `copilot`     | `ccusage copilot daily`     |
| Gemini CLI     | `gemini`      | `ccusage gemini daily`      |
| Antigravity    | `antigravity` | `ccusage antigravity daily` |
| Grok Build CLI | `grok`        | `ccusage grok daily`        |
| ZCode          | `zcode`       | `ccusage zcode daily`       |

## When to Focus a Source

Use a source namespace when you want source-specific options or when you are debugging one local data format:

```bash
ccusage codex daily --speed fast
ccusage claude daily --mode display
ccusage opencode session --json
ccusage amp monthly --compact
ccusage droid session
ccusage codebuff daily
ccusage pi session --pi-path /path/to/sessions
ccusage openclaw daily --open-claw-path /path/to/openclaw
ccusage kilo session
ccusage qwen daily
ccusage copilot daily --json
ccusage gemini session --json
ccusage grok daily --json
ccusage zcode daily --json
```

## Next Steps

* [Daily Usage](/guide/daily-reports) - Calendar-day usage
* [Weekly Usage](/guide/weekly-reports) - Week-by-week usage
* [Monthly Usage](/guide/monthly-reports) - Longer-term usage trends
* [Session Usage](/guide/session-reports) - Per-conversation usage
* [Data Sources](/guide/#data-sources) - Supported local data formats
* [Source Support Q\&A](/guide/source-support-qa) - Why some investigated CLIs are not supported

---

---
url: /guide/daily-reports.md
---
# Daily Usage

![Daily usage report showing token usage and costs by date with model breakdown](/screenshot.png)

Daily usage shows token usage and estimated costs aggregated by calendar date. By default, `ccusage daily` combines every detected supported data source; use `ccusage <source> daily` when you want one source.

## Basic Usage

Show all daily usage:

```bash
ccusage daily
# or simply:
ccusage

# Focus on one source:
ccusage codex daily
ccusage opencode daily
ccusage amp daily
ccusage pi daily
ccusage qwen daily
```

The daily command is the default, so you can omit it when running ccusage.

## Example Output

![Daily usage report showing token usage and costs by date with model breakdown](/screenshot.png)

## Understanding the Columns

### Basic Columns

* **Date**: Calendar date in YYYY-MM-DD format
* **Agent**: Source CLI for unified reports
* **Models**: Models used that day (shown as a bulleted list)
* **Input**: Total input tokens sent to the model
* **Output**: Total output tokens received from the model
* **Cost (USD)**: Estimated cost for that day

### Cache Columns

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

### Responsive Display

ccusage automatically adapts to your terminal width:

* **Wide terminals (≥100 chars)**: Shows all columns
* **Narrow terminals (<100 chars)**: Compact mode with essential columns only

## Command Options

### Date Filtering

Filter reports by date range:

```bash
# Show usage from May 2026
ccusage daily --since 20260501 --until 20260516

# Show last week
ccusage daily --since 20260510 --until 20260516

# Show usage since a specific date
ccusage daily --since 20260501
```

### Recent Days

Skip the date arithmetic when you only want the days just gone:

```bash
# Today
ccusage daily --last 1

# The last seven days, including today
ccusage daily --last 7
```

`--last` cannot be combined with `--since` or `--until`. See [Command-Line Options](/guide/cli-options#recent-periods) for how it behaves on the other reports.

### Sort Order

Control the order of dates:

```bash
# Newest dates first (default)
ccusage daily --order desc

# Oldest dates first
ccusage daily --order asc
```

### Cost Calculation Modes

Control how costs are calculated:

```bash
# Use pre-calculated costs when available (default)
ccusage daily --mode auto

# Always calculate costs from tokens
ccusage daily --mode calculate

# Only show pre-calculated costs
ccusage daily --mode display
```

### Model Breakdown

See per-model cost breakdown:

```bash
ccusage daily --breakdown
```

This shows costs split by individual models:

```
┌──────────────┬──────────────────┬────────┬─────────┬────────────┐
│ Date         │ Models           │ Input  │ Output  │ Cost (USD) │
├──────────────┼──────────────────┼────────┼─────────┼────────────┤
│ 2026-05-16   │ opus-4-1, sonnet-4-5 │    277 │  31,456 │     $17.58 │
├──────────────┼──────────────────┼────────┼─────────┼────────────┤
│   └─ opus-4-1  │                  │    100 │  15,000 │     $10.25 │
├──────────────┼──────────────────┼────────┼─────────┼────────────┤
│   └─ sonnet-4-5│                  │    177 │  16,456 │      $7.33 │
└──────────────┴──────────────────┴────────┴─────────┴────────────┘
```

### JSON Output

Export data as JSON for further analysis:

```bash
ccusage daily --json
```

```json
{
	"type": "daily",
	"data": [
		{
			"date": "2026-05-16",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 277,
			"outputTokens": 31456,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 33269,
			"costUSD": 17.58
		}
	],
	"summary": {
		"totalInputTokens": 277,
		"totalOutputTokens": 31456,
		"totalCacheCreationTokens": 512,
		"totalCacheReadTokens": 1024,
		"totalTokens": 33269,
		"totalCostUSD": 17.58
	}
}
```

### Offline Mode

Use cached pricing data without network access:

```bash
ccusage daily --offline
# or short form:
ccusage daily -O
```

### Project Analysis

Group usage by project instead of aggregating across all projects:

```bash
# Group daily usage by project
ccusage daily --instances
ccusage daily -i
```

When using `--instances`, the report shows usage for each project separately:

```
┌──────────────┬────────────────────────────────────────────────────────────────────────────────────────────┐
│ Project: my-project                                                                                     │
├──────────────┬──────────────────┬────────┬─────────┬────────────┬────────────┬─────────────┬──────────┤
│ Date         │ Models           │ Input  │ Output  │ Cache Create│ Cache Read │ Total Tokens│ Cost (USD)│
├──────────────┼──────────────────┼────────┼─────────┼────────────┼────────────┼─────────────┼──────────┤
│ 2026-05-16   │ • sonnet-4-5       │    277 │  31,456 │         512│      1,024 │      33,269 │     $7.33│
└──────────────┴──────────────────┴────────┴─────────┴────────────┴────────────┴─────────────┴──────────┘

┌──────────────┬────────────────────────────────────────────────────────────────────────────────────────────┐
│ Project: other-project                                                                                  │
├──────────────┬──────────────────┬────────┬─────────┬────────────┬────────────┬─────────────┬──────────┤
│ Date         │ Models           │ Input  │ Output  │ Cache Create│ Cache Read │ Total Tokens│ Cost (USD)│
├──────────────┼──────────────────┼────────┼─────────┼────────────┼────────────┼─────────────┼──────────┤
│ 2026-05-16   │ • opus-4-1         │    100 │  15,000 │         256│        512 │      15,868 │    $10.25│
└──────────────┴──────────────────┴────────┴─────────┴────────────┴────────────┴─────────────┴──────────┘
```

Filter to a specific project:

```bash
# Show only usage from "my-project"
ccusage daily --project my-project
ccusage daily -p my-project

# Combine with instances flag
ccusage daily --instances --project my-project
```

## Common Use Cases

### Track Monthly Spending

```bash
# See May 2026 usage
ccusage daily --since 20260501 --until 20260516
```

### Find Expensive Days

```bash
# Sort by cost (highest first)
ccusage daily --order desc
```

### Export for Spreadsheet Analysis

```bash
ccusage daily --json > may-usage.json
```

### Compare Model Usage

```bash
# See which models you use most
ccusage daily --breakdown
```

### Check Recent Activity

```bash
# Last 7 days
ccusage daily --since $(date -d '7 days ago' +%Y%m%d)
```

### Analyze Project Usage

```bash
# See usage breakdown by project
ccusage daily --instances

# Track specific project costs
ccusage daily --project my-important-project --since 20260501

# Compare project usage with JSON export
ccusage daily --instances --json > project-analysis.json
```

### Team Usage Analysis

Use project aliases to replace cryptic or long project directory names with readable labels:

```json
// .ccusage/ccusage.json - Set custom project names for better reporting
{
	"commands": {
		"daily": {
			"projectAliases": "uuid-project=Frontend App,long-name=Backend API"
		}
	}
}
```

The `projectAliases` setting uses a comma-separated format of `original-name=display-name` pairs. This is especially useful when:

* Your projects have UUID-based names (e.g., `a2cd99ed-a586=My App`)
* Directory names are long paths that get truncated
* You want consistent naming across team reports

```bash
# Generate team report with readable project names
ccusage daily --instances --since 20260501
# Now shows "Frontend App" instead of "uuid-project"
```

## Tips

1. **Compact Mode**: If your terminal is narrow, expand it to see all columns
2. **Date Format**: Use YYYYMMDD format for date filters (e.g., 20260516)
3. **Regular Monitoring**: Run daily reports regularly to track usage patterns
4. **JSON Export**: Use `--json` for creating charts or additional analysis

## Related Commands

* [All Sources (Default)](/guide/all-reports) - How unified views work
* [Monthly Usage](/guide/monthly-reports) - Aggregate by month
* [Session Usage](/guide/session-reports) - Per-conversation analysis
* [Claude Code](/guide/claude/) - Claude Code-specific setup and features

---

---
url: /guide/weekly-reports.md
---
# Weekly Usage

Weekly usage aggregates usage by week, providing a mid-range view between daily and monthly usage. `ccusage weekly` covers all detected sources that support weekly aggregation; `ccusage claude weekly` and `ccusage opencode weekly` focus the same view on one source.

## Basic Usage

Show all weekly usage:

```bash
ccusage weekly
ccusage claude weekly
ccusage opencode weekly
```

## Example Output

```text
┌────────────────┬──────────────────────┬────────┬─────────┬─────────────┬────────────┬──────────────┬────────────┐
│ Week           │ Models               │ Input  │ Output  │ Cache Create│ Cache Read │ Total Tokens │ Cost (USD) │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-11     │ • opus-4-1           │  1,234 │ 156,789 │       2,048 │      4,096 │      164,167 │     $87.56 │
│                │ • sonnet-4-5         │        │         │             │            │              │            │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-04     │ • sonnet-4-5         │  2,456 │ 234,567 │       3,072 │      6,144 │      246,239 │    $104.33 │
├────────────────┼──────────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2026-04-27     │ • opus-4-1           │  3,789 │ 345,678 │       4,096 │      8,192 │      361,755 │    $156.78 │
│                │ • sonnet-4-5         │        │         │             │            │              │            │
└────────────────┴──────────────────────┴────────┴─────────┴─────────────┴────────────┴──────────────┴────────────┘
```

## Understanding the Columns

The columns are identical to daily reports but aggregated by week:

* **Week**: Start date of the week (configurable)
* **Agent**: Source CLI, shown in unified all-source reports
* **Models**: All models used during the week
* **Input/Output**: Total tokens for the week
* **Cache Create/Read**: Cache token usage
* **Total Tokens**: Sum of all token types
* **Cost (USD)**: Estimated cost for the week

## Command Options

### Week Start Day

Configure which day starts the week:

```bash
# Start week on Monday (default for ccusage weekly)
ccusage weekly --start-of-week monday
ccusage weekly -w monday

# Start week on Sunday
ccusage weekly --start-of-week sunday

# ccusage claude weekly starts on Sunday by default
ccusage claude weekly

# Other options: tuesday, wednesday, thursday, friday, saturday
```

### Date Filtering

Filter by date range:

```bash
# Show specific period
ccusage weekly --since 20260501 --until 20260531

# Show last 4 weeks
ccusage weekly --since 20260420
```

### Recent Weeks

Count back in whole weeks instead of dates:

```bash
# This week so far
ccusage weekly --last 1

# This week and the three before it
ccusage weekly --last 4
```

The window starts on the same weekday the report buckets by, so `ccusage claude weekly --last 1 -w monday` starts on Monday. `--last` cannot be combined with `--since` or `--until`.

### Sort Order

Control the order of weeks:

```bash
# Newest weeks first (default)
ccusage weekly --order desc

# Oldest weeks first
ccusage weekly --order asc
```

### Model Breakdown

See per-model weekly costs:

```bash
ccusage weekly --breakdown
```

```text
┌────────────────┬──────────────────────┬────────┬─────────┬────────────┐
│ Week           │ Models               │ Input  │ Output  │ Cost (USD) │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│ 2026-05-11     │ opus-4-1, sonnet-4-5 │  1,234 │ 156,789 │     $87.56 │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│   └─ opus-4-1  │                      │    800 │  80,000 │     $54.80 │
├────────────────┼──────────────────────┼────────┼─────────┼────────────┤
│   └─ sonnet-4-5│                      │    434 │  76,789 │     $32.76 │
└────────────────┴──────────────────────┴────────┴─────────┴────────────┘
```

### JSON Output

Export weekly data as JSON:

```bash
ccusage weekly --json
```

```json
{
	"weekly": [
		{
			"week": "2026-05-11",
			"inputTokens": 1234,
			"outputTokens": 156789,
			"cacheCreationTokens": 2048,
			"cacheReadTokens": 4096,
			"totalTokens": 164167,
			"totalCost": 87.56,
			"modelsUsed": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"modelBreakdowns": {
				"claude-opus-4-1-20250805": {
					"inputTokens": 800,
					"outputTokens": 80000,
					"totalCost": 54.8
				},
				"claude-sonnet-4-5-20250929": {
					"inputTokens": 434,
					"outputTokens": 76789,
					"totalCost": 32.76
				}
			}
		}
	],
	"totals": {
		"inputTokens": 7479,
		"outputTokens": 737034,
		"cacheCreationTokens": 9216,
		"cacheReadTokens": 18432,
		"totalTokens": 772161,
		"totalCost": 348.67
	}
}
```

### Project Analysis

Group weekly usage by project:

```bash
# Show weekly usage per project
ccusage weekly --instances

# Filter to specific project
ccusage weekly --project my-project
```

### Cost Calculation Modes

Control cost calculation:

```bash
# Auto mode (default)
ccusage weekly --mode auto

# Always calculate from tokens
ccusage weekly --mode calculate

# Only use pre-calculated costs
ccusage weekly --mode display
```

### Offline Mode

Use cached pricing data:

```bash
ccusage weekly --offline
```

## Common Use Cases

### Weekly Trends

```bash
# See usage trends over past months
ccusage weekly --since 20260401
```

### Sprint Analysis

```bash
# Track usage during 2-week sprints (Monday start)
ccusage weekly --start-of-week monday --since 20260501
```

### Budget Planning

```bash
# Export for weekly budget tracking
ccusage weekly --json > weekly-budget.json
```

### Compare Workweeks

```bash
# Monday-Friday work pattern analysis
ccusage weekly --start-of-week monday --breakdown
```

### Team Reporting

```bash
# Weekly team usage report
ccusage weekly --instances --start-of-week monday
```

## Tips

1. **Week Start**: Choose a start day that aligns with your work schedule
2. **Breakdown View**: Use `--breakdown` to identify which models drive costs
3. **JSON Export**: Weekly JSON data is perfect for creating trend charts
4. **Project Tracking**: Use `--instances` to track project-specific weekly usage

## Related Commands

* [All Sources (Default)](/guide/all-reports) - How unified views work
* [Daily Usage](/guide/daily-reports) - Day-by-day analysis
* [Monthly Usage](/guide/monthly-reports) - Monthly aggregates
* [Session Usage](/guide/session-reports) - Per-conversation analysis

---

---
url: /guide/monthly-reports.md
---
# Monthly Usage

Monthly usage aggregates coding (agent) CLI usage by calendar month, providing a high-level view of usage patterns and estimated costs over longer periods. `ccusage monthly` combines all detected supported sources; use `ccusage <source> monthly` for a single source.

## Basic Usage

```bash
ccusage monthly
ccusage codex monthly
ccusage amp monthly
ccusage pi monthly
ccusage qwen monthly
```

## Example Output

```
╭─────────────────────────────────────────────╮
│                                             │
│  Claude Code Token Usage Report - Monthly  │
│                                             │
╰─────────────────────────────────────────────╯

┌─────────┬────────────────────┬─────────┬──────────┬──────────────┬────────────┬──────────────┬────────────┐
│ Month   │ Models             │ Input   │ Output   │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├─────────┼────────────────────┼─────────┼──────────┼──────────────┼────────────┼──────────────┼────────────┤
│ 2026-05 │ • opus-4-1         │  45,231 │  892,456 │        2,048 │      4,096 │      943,831 │   $1,247.92│
│         │ • sonnet-4-5       │         │          │              │            │              │            │
│ 2026-04 │ • sonnet-4-5       │  38,917 │  756,234 │        1,536 │      3,072 │      799,759 │     $892.15│
│ 2026-03 │ • opus-4-1         │  22,458 │  534,789 │        1,024 │      2,048 │      560,319 │     $678.43│
├─────────┼────────────────────┼─────────┼──────────┼──────────────┼────────────┼──────────────┼────────────┤
│ Total   │                  │ 106,606 │2,183,479 │        4,608 │      9,216 │    2,303,909 │   $2,818.50│
└─────────┴────────────────────┴─────────┴──────────┴──────────────┴────────────┴──────────────┴────────────┘
```

## Understanding Monthly Data

### Month Format

Months are displayed in YYYY-MM format:

* `2026-05` = May 2026
* `2026-04` = April 2026

### Aggregation Logic

All usage within a calendar month is aggregated:

* Input/output tokens summed across all days
* Costs calculated from total token usage
* Models listed if used at any point in the month

## Command Options

### Date Filtering

Filter by month range:

```bash
# Show specific months
ccusage monthly --since 20260101 --until 20260531

# Show usage from Jan-May 2026
ccusage monthly --since 20260101 --until 20260531

# Show last 6 months
ccusage monthly --since $(date -d '6 months ago' +%Y%m%d)
```

::: tip Date Filtering
Even though you specify full dates (YYYYMMDD), monthly reports group by month. The filters determine which months to include.
:::

### Recent Months

`--last` counts whole months, so the shell date arithmetic above is not needed:

```bash
# This month so far
ccusage monthly --last 1

# This month and the five before it
ccusage monthly --last 6
```

`--last` cannot be combined with `--since` or `--until`.

### Sort Order

```bash
# Newest months first (default)
ccusage monthly --order desc

# Oldest months first
ccusage monthly --order asc
```

### Cost Calculation Modes

```bash
# Use pre-calculated costs when available (default)
ccusage monthly --mode auto

# Always calculate costs from tokens
ccusage monthly --mode calculate

# Only show pre-calculated costs
ccusage monthly --mode display
```

### Model Breakdown

See costs broken down by model:

```bash
ccusage monthly --breakdown
```

Example with breakdown:

```
┌─────────┬──────────────────────┬─────────┬──────────┬────────────┐
│ Month   │ Models               │ Input   │ Output   │ Cost (USD) │
├─────────┼──────────────────────┼─────────┼──────────┼────────────┤
│ 2026-05 │ opus-4-1, sonnet-4-5 │  45,231 │  892,456 │  $1,247.92 │
├─────────┼──────────────────────┼─────────┼──────────┼────────────┤
│  └─ opus-4-1                   │  20,000 │  400,000 │    $750.50 │
├─────────┼──────────────────────┼─────────┼──────────┼────────────┤
│  └─ sonnet-4-5                 │  25,231 │  492,456 │    $497.42 │
└─────────┴──────────────────────┴─────────┴──────────┴────────────┘
```

### JSON Output

```bash
ccusage monthly --json
```

```json
[
	{
		"month": "2026-05",
		"models": ["opus-4-1", "sonnet-4-5"],
		"inputTokens": 45231,
		"outputTokens": 892456,
		"cacheCreationTokens": 2048,
		"cacheReadTokens": 4096,
		"totalTokens": 943831,
		"totalCost": 1247.92
	}
]
```

### Offline Mode

```bash
ccusage monthly --offline
```

## Analysis Use Cases

### Budget Planning

Monthly reports help with subscription planning:

```bash
# Check last year's usage
ccusage monthly --since 20250101 --until 20251231
```

Look at the total cost to understand what you'd pay on usage-based pricing.

### Usage Trends

Track how your usage changes over time:

```bash
# Compare year over year
ccusage monthly --since 20240101 --until 20241231  # 2024
ccusage monthly --since 20250101 --until 20251231  # 2025
```

### Model Migration Analysis

See how your model usage evolves:

```bash
ccusage monthly --breakdown
```

This helps track transitions between Opus 4.1, Sonnet 4.5, and other models.

### Seasonal Patterns

Identify busy/slow periods:

```bash
# Academic year analysis
ccusage monthly --since 20250901 --until 20260531
```

### Export for Business Analysis

```bash
# Create quarterly reports
ccusage monthly --since 20260101 --until 20260331 --json > q1-2026.json
```

## Tips for Monthly Analysis

### 1. Cost Context

Monthly totals show:

* **Subscription Value**: How much you'd pay with usage-based billing
* **Usage Intensity**: Months with heavy coding CLI usage
* **Model Preferences**: Which models you favor over time

### 2. Trend Analysis

Look for patterns:

* Increasing usage over time
* Seasonal variations
* Model adoption curves

### 3. Business Planning

Use monthly data for:

* Team budget planning
* Usage forecasting
* Subscription optimization

### 4. Comparative Analysis

Compare monthly reports with:

* Team productivity metrics
* Project timelines
* Business outcomes

## Related Commands

* [All Sources (Default)](/guide/all-reports) - How unified views work
* [Daily Usage](/guide/daily-reports) - Day-by-day breakdown
* [Session Usage](/guide/session-reports) - Individual conversations
* [Claude Code](/guide/claude/) - Claude Code-specific setup and features

## Next Steps

After analyzing monthly trends, consider:

1. [Session Usage](/guide/session-reports) to identify high-cost conversations
2. [Claude Code](/guide/claude/) for Claude Code-specific setup and features
3. [JSON Output](/guide/json-output) for programmatic analysis

---

---
url: /guide/session-reports.md
---
# Session Usage

Session usage shows usage grouped by individual conversations, threads, or sessions. `ccusage session` combines all detected supported sources; use `ccusage <source> session` to inspect one source's session format.

## Basic Usage

```bash
ccusage session
ccusage codex session
ccusage opencode session
ccusage amp session
ccusage pi session
ccusage qwen session
```

## Specific Session Lookup

Query individual session details by providing a session ID:

```bash
ccusage claude session --id <session-id>
ccusage codex session --id <session-id>
```

This is particularly useful for:

* **Custom statuslines**: Integrate specific session data into your development environment
* **Programmatic usage**: Extract session metrics for scripts and automation
* **Detailed analysis**: Get comprehensive data about a single conversation

### Examples

```bash
# Get session data in table format
ccusage claude session --id session-abc123-def456

# Get session data as JSON for scripting
ccusage codex session --id codex://threads/01a0bb8c-c7c0-7630-9d82-860b875930f0 --json

# Extract just the cost using jq
ccusage codex session --id 01a0bb8c-c7c0-7630-9d82-860b875930f0 --json | jq '.totalCost'

# Use in a custom statusline script
COST=$(ccusage claude session --id "$SESSION_ID" --json | jq '.totalCost')
echo "Current session: \$${COST}"
```

### Session ID Format

For Claude Code, session IDs are the actual filenames (without `.jsonl` extension) stored in Claude data directories. They typically look like:

* `session-20260516-abc123-def456`
* `project-conversation-xyz789`

You can find Claude session IDs by running `ccusage claude session` and looking for the files in your Claude data directory.

For Codex, use the `sessionId` from `ccusage codex session --json`. The lookup accepts that full ID, its JSONL filename with or without the `.jsonl` or `.jsonl.zst` extension, the trailing UUID, or a `codex://threads/<uuid>` URI. A shortened UUID is not accepted, and a UUID that matches more than one session is reported as ambiguous.

## Example Output

```
╭───────────────────────────────────────────────╮
│                                               │
│  Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯

┌────────────┬────────────────────┬────────┬─────────┬──────────────┬────────────┬──────────────┬────────────┬───────────────┐
│ Session    │ Models             │ Input  │ Output  │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │ Last Activity │
├────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
│ abc123-def │ • opus-4-1         │  4,512 │ 350,846 │          512 │      1,024 │      356,894 │    $156.40 │ 2026-05-16    │
│            │ • sonnet-4-5       │        │         │              │            │              │            │               │
│ ghi456-jkl │ • sonnet-4-5       │  2,775 │ 186,645 │          256 │        768 │      190,444 │     $98.45 │ 2026-05-15    │
│ mno789-pqr │ • opus-4-1         │  1,887 │ 183,055 │          128 │        512 │      185,582 │     $81.73 │ 2026-05-14    │
├────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
│ Total      │                  │  9,174 │ 720,546 │          896 │      2,304 │      732,920 │    $336.58 │               │
└────────────┴────────────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┴───────────────┘
```

## Understanding Session Data

### Session Identification

Sessions are displayed using the last two segments of their full identifier:

* Full session ID: `project-20260516-session-abc123-def456`
* Displayed as: `abc123-def`

### Session Metrics

* **Input/Output Tokens**: Total tokens exchanged in the conversation
* **Cache Tokens**: Cache creation and read tokens for context efficiency
* **Cost**: Estimated USD cost for the usage shown; without a date filter, the entire conversation
* **Last Activity**: Date of the most recent message included in the report

### Sorting

Unified session reports are sorted by cost (highest first) by default. Use `ccusage session --order asc` for lowest cost first or `--order desc` for highest cost first. Equal costs sort by session ID, then agent, in ascending order.

The `order` configuration option also controls this direction; an explicit CLI flag takes precedence. With mixed `--sections` reports, the selected order applies to session costs and chronological periods. Without an order option, sessions use descending cost while daily, weekly, and monthly sections stay chronological (ascending).

## Command Options

### Session ID Lookup

Get detailed information about a specific session:

```bash
# Query a specific session by ID
ccusage claude session --id <session-id>
ccusage codex session --id <session-id>

# Get JSON output for a specific session
ccusage codex session --id <session-id> --json

# Short form using -i flag
ccusage codex session -i <session-id>
```

**Use cases:**

* Building custom statuslines that show current session costs
* Creating scripts that monitor specific conversation expenses
* Debugging or analyzing individual conversation patterns
* Integrating session data into development workflows

### Date Filtering

For Claude Code, filter session usage by the local date of each entry:

```bash
# Show sessions active since May 10th
ccusage claude session --since 20260510

# Show sessions active in a specific date range
ccusage claude session --since 20260501 --until 20260516

# Show only recent sessions (last week)
ccusage claude session --since $(date -d '7 days ago' +%Y%m%d)
```

For `ccusage claude session`, date filters are applied before session totals are calculated, so token and cost totals represent only the entries inside the selected window. Both bounds are inclusive, and `--timezone` determines the local date used for filtering.

### Cost Calculation Modes

```bash
# Use pre-calculated costs when available (default)
ccusage session --mode auto

# Always calculate costs from tokens
ccusage session --mode calculate

# Only show pre-calculated costs
ccusage session --mode display
```

### Model Breakdown

See per-model cost breakdown within each session:

```bash
ccusage session --breakdown
```

Example with breakdown:

```
┌───────────────┬──────────────────────┬────────┬─────────┬────────────┬───────────────┐
│ Session       │ Models               │ Input  │ Output  │ Cost (USD) │ Last Activity │
├───────────────┼──────────────────────┼────────┼─────────┼────────────┼───────────────┤
│ abc123-def    │ opus-4-1, sonnet-4-5 │  4,512 │ 350,846 │    $156.40 │ 2026-05-16    │
├───────────────┼──────────────────────┼────────┼─────────┼────────────┼───────────────┤
│   └─ opus-4-1 │                      │  2,000 │ 200,000 │     $95.50 │               │
├───────────────┼──────────────────────┼────────┼─────────┼────────────┼───────────────┤
│   └─ sonnet-4-5                      │  2,512 │ 150,846 │     $60.90 │               │
└───────────────┴──────────────────────┴────────┴─────────┴────────────┴───────────────┘
```

### JSON Output

Export session data as JSON for further analysis:

```bash
ccusage session --json
```

```json
{
	"sessions": [
		{
			"sessionId": "abc123-def",
			"inputTokens": 4512,
			"outputTokens": 350846,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 356894,
			"totalCost": 156.4,
			"firstActivity": "2026-05-15T09:30:00.000Z",
			"lastActivity": "2026-05-16T17:45:30.000Z",
			"modelsUsed": ["opus-4-1", "sonnet-4-5"],
			"modelBreakdowns": [
				{
					"model": "opus-4-1",
					"inputTokens": 2000,
					"outputTokens": 200000,
					"totalCost": 95.5
				}
			]
		}
	],
	"totals": {
		"inputTokens": 9174,
		"outputTokens": 720546,
		"totalCost": 336.58
	}
}
```

### Offline Mode

Use cached pricing data without network access:

```bash
ccusage session --offline
# or short form:
ccusage session -O
```

## Analysis Use Cases

### Identify Expensive Conversations

Session reports help you understand which conversations are most costly:

```bash
ccusage session
```

Look at the top sessions to understand:

* Which types of conversations cost the most
* Whether long coding sessions or research tasks are more expensive
* How model choice (Opus 4.1 vs Sonnet 4.5) affects costs

### Track Conversation Patterns

```bash
# See recent conversation activity
ccusage session --since 20260510

# Compare different time periods
ccusage session --since 20260501 --until 20260515  # First half of month
ccusage session --since 20260516 --until 20260531  # Second half of month
```

### Model Usage Analysis

```bash
# See which models you use in different conversations
ccusage session --breakdown
```

This helps understand:

* Whether you prefer Opus 4.1 for complex tasks
* If Sonnet 4.5 is sufficient for routine work
* How model mixing affects total costs

### Budget Optimization

```bash
# Export data for spreadsheet analysis
ccusage session --json > sessions.json

# Find sessions above a certain cost threshold
ccusage session --json | jq '.sessions[] | select(.totalCost > 50)'
```

## Tips for Session Analysis

### 1. Cost Context Understanding

Session costs help you understand:

* **Conversation Value**: High-cost sessions should provide proportional value
* **Efficiency Patterns**: Some conversation styles may be more token-efficient
* **Model Selection**: Whether your model choices align with task complexity

### 2. Usage Optimization

Use session data to:

* **Identify expensive patterns**: What makes some conversations cost more?
* **Optimize conversation flow**: Break long sessions into smaller focused chats
* **Choose appropriate models**: Use Sonnet 4.5 for simpler tasks, Opus 4.1 for complex ones

### 3. Budget Planning

Session analysis helps with:

* **Conversation budgeting**: Understanding typical session costs
* **Usage forecasting**: Predicting monthly costs based on session patterns
* **Value assessment**: Ensuring expensive sessions provide good value

### 4. Comparative Analysis

Compare sessions to understand:

* **Task types**: Coding vs writing vs research costs
* **Model effectiveness**: Whether Opus 4.1 provides value over Sonnet 4.5
* **Time patterns**: Whether longer sessions are more or less efficient

## Responsive Display

Session reports adapt to your terminal width:

* **Wide terminals (≥100 chars)**: Shows all columns including cache metrics
* **Narrow terminals (<100 chars)**: Compact mode with essential columns (Session, Models, Input, Output, Cost, Last Activity)

When in compact mode, ccusage displays a message explaining how to see the full data.

## Related Commands

* [All Sources (Default)](/guide/all-reports) - How unified views work
* [Daily Usage](/guide/daily-reports) - Usage aggregated by date
* [Monthly Usage](/guide/monthly-reports) - Monthly summaries
* [Claude Code](/guide/claude/) - Claude Code-specific setup and features

## Next Steps

After analyzing session patterns, consider:

1. [Daily Usage](/guide/daily-reports) to see how session patterns vary by day
2. [Monthly Usage](/guide/monthly-reports) to compare longer-term patterns
3. [Claude Code](/guide/claude/) for Claude Code-specific setup and features

---

---
url: /guide/claude.md
---
# Claude Code Data Source

ccusage can read Claude Code usage data as one of its supported local data sources. Claude Code is no longer treated as the only ccusage target; it uses the same unified and focused report model as Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI.

## Focused Views

```bash
# Daily Claude Code usage
ccusage claude daily

# Weekly Claude Code usage
ccusage claude weekly

# Monthly Claude Code usage
ccusage claude monthly

# Claude Code sessions
ccusage claude session
```

Most users can start with unified reports such as `ccusage daily`. Add the `claude` namespace only when you want to focus the same report shape on Claude Code usage or pass Claude-specific options.

## Data Source

ccusage reads Claude Code project logs from the standard Claude data directories:

| Source      | Default paths                                       |
| ----------- | --------------------------------------------------- |
| Claude Code | `~/.config/claude/projects/`, `~/.claude/projects/` |

The tool checks both locations and combines valid data. When `CLAUDE_CONFIG_DIR` is set, that value replaces the default lookup and can contain one directory or a comma-separated list of directories.

::: warning Retention
Claude Code can retain logs for only 30 days by default. To review older Claude Code usage, change `cleanupPeriodDays` in your Claude Code settings.

[Claude Code settings - Claude Docs](https://docs.claude.com/en/docs/claude-code/settings#settings-files)
:::

## Report Views

| Focused view             | Description                   | See also                                |
| ------------------------ | ----------------------------- | --------------------------------------- |
| `ccusage claude daily`   | Aggregate usage by date       | [Daily Usage](/guide/daily-reports)     |
| `ccusage claude weekly`  | Aggregate usage by week       | [Weekly Usage](/guide/weekly-reports)   |
| `ccusage claude monthly` | Aggregate usage by month      | [Monthly Usage](/guide/monthly-reports) |
| `ccusage claude session` | Group usage by Claude session | [Session Usage](/guide/session-reports) |

## Claude Code Features

Claude Code exposes additional local data that enables features beyond the shared report views:

* [Blocks](/guide/blocks-reports) - Claude Code 5-hour billing window analysis
* [Statusline](/guide/statusline) - Compact real-time usage display for Claude Code status bar hooks

## Environment Variables

| Variable            | Description                                  |
| ------------------- | -------------------------------------------- |
| `CLAUDE_CONFIG_DIR` | Override the root Claude Code data directory |
| `LOG_LEVEL`         | Adjust verbosity (0 silent ... 5 trace)      |

### Custom Claude Code Paths

Set `CLAUDE_CONFIG_DIR` when Claude Code logs live outside the default locations:

```bash
export CLAUDE_CONFIG_DIR="/path/to/your/claude/data"
ccusage claude daily
```

Use comma-separated directories to combine current and archived Claude Code data:

```bash
export CLAUDE_CONFIG_DIR="~/.config/claude,/backup/claude-archive"
ccusage claude monthly
```

For Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI data locations, use the source-specific environment variables listed in [Environment Variables](/guide/environment-variables).

### Directory Detection

When `CLAUDE_CONFIG_DIR` is not set, ccusage searches in this order:

1. `~/.config/claude/projects/`
2. `~/.claude/projects/`

Data from all valid directories is combined automatically.

## Troubleshooting

::: details No Claude Code usage data found
Check whether your logs live under `~/.config/claude/projects/` or `~/.claude/projects/`. If your data lives elsewhere, set `CLAUDE_CONFIG_DIR` or use the relevant path option.
:::

---

---
url: /guide/codex.md
---
# Codex Data Source (Beta)

![ccusage daily report focused on Codex usage](/codex-cli.jpeg)

> ⚠️ Codex log support is experimental while the Codex CLI log format continues to evolve.

ccusage can read OpenAI Codex CLI session logs as one of its supported local data sources. Codex uses the same unified and focused report model as Claude Code, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI.

## Focused Views

```bash
# Daily Codex usage
ccusage codex daily

# Monthly Codex usage
ccusage codex monthly

# Codex sessions
ccusage codex session
```

Most users can start with unified reports such as `ccusage daily`. Add the `codex` namespace only when you want to focus the same report shape on Codex usage or pass Codex-specific options such as `--speed`.

## Data Source

The CLI reads Codex session JSONL files, both plain `.jsonl` and Zstandard-compressed `.jsonl.zst`, located under `CODEX_HOME` (defaults to `~/.codex`). `CODEX_HOME` can be one directory or a comma-separated list of directories. For each entry, ccusage discovers `sessions/` and `archived_sessions/` independently, so an entry with only `archived_sessions/` still contributes archived Codex logs. When neither directory exists, the entry is read directly as a JSONL directory, which lets saved `codex exec --json` output live beside normal Codex homes. Compression does not change a session ID. Within one directory, when a plain and a compressed copy of the same rollout both exist, the plain copy is read and the compressed one is skipped, matching Codex. If the same relative rollout path exists in both `sessions/` and `archived_sessions/` for one Codex home, the active `sessions/` copy wins regardless of encoding, so archived copies are not double counted.

```bash
CODEX_HOME="$HOME/.codex,$HOME/.codex-work,$HOME/codex-exec-logs" ccusage codex daily
```

## Report Views

| Focused view            | Description                  | See also                                |
| ----------------------- | ---------------------------- | --------------------------------------- |
| `ccusage codex daily`   | Aggregate usage by date      | [Daily Usage](/guide/daily-reports)     |
| `ccusage codex monthly` | Aggregate usage by month     | [Monthly Usage](/guide/monthly-reports) |
| `ccusage codex session` | Group usage by Codex session | [Session Usage](/guide/session-reports) |

These views support `--json`, `--compact`, `--offline`, and `--speed auto|standard|flex|fast`.

## Monthly Example

![ccusage monthly report focused on Codex usage](/codex-cli-monthly.jpeg)

## What Gets Calculated

* **Token deltas** – Each `event_msg` with `payload.type === "token_count"` reports cumulative totals and, when available, the latest request delta. Current MultiAgent V2 subagent rollouts can persist a replayed parent-history prefix; the CLI uses the final inherited snapshot as the child baseline, then counts only advancing usage from the child turn. Older Codex replay formats retain timestamp-based compatibility handling.
* **Automatic compaction** – Codex can record remote compaction requests separately from cumulative token counts. ccusage includes a `token_usage_record` only when its response ID matches a `compacted` record and the intervening token-count snapshot has not already accounted for it. Copied response IDs are counted once across reports, including when the parent session is outside the selected date range. A missing model uses the active `turn_context` and is marked as a fallback estimate. Additional compaction usage does not change the normal cumulative baseline.
* **Per-model grouping** – The active `turn_context` specifies the model for newly counted usage. Replayed parent contexts in current MultiAgent V2 subagent prefixes remain inherited history and do not add model usage to the child. We aggregate tokens per day/month and per model. Sessions lacking model metadata (seen in early September 2025 builds) are skipped.
* **Pricing** – Rates come from LiteLLM's pricing dataset via the shared `LiteLLMPricingFetcher`. Codex's internal review label uses the manually curated, date-based fallback timeline below and remains marked as approximate.
* **Scheduled pricing** – DeepSeek V4 Flash and Pro use each event's timestamp: legacy rates apply before `2026-08-16T16:00:00Z`, and the later rates use UTC weekday peak windows of `01:00–04:00` and `06:00–10:00` (endpoints excluded). Cache creation follows the scheduled input rate.
* **Speed pricing** uses `--speed auto` by default. For rollouts written by Codex CLI 0.144.0 and later, ccusage applies recorded `thread_settings_applied` tier changes chronologically. `priority` and legacy `fast` use Fast pricing, `flex` uses Flex pricing, and `default` or `standard` uses Standard pricing. Unmarked usage falls back to `config.toml` detection. Pass `--speed standard`, `--speed flex`, or `--speed fast` to override every recorded tier. Fast and Flex pricing use model-specific multipliers only when one is available; otherwise, ccusage keeps standard pricing rather than inventing a rate.
* **Legacy fallback** – Early September 2025 logs that never recorded `turn_context` metadata are still included; the CLI assumes `gpt-5` for pricing so you can review the tokens even though the model tag is missing (the JSON output also marks these rows with `"isFallback": true`).
* **Cost formula** – Non-cached input uses the standard input price; cached input uses the cache-read price (falling back to the input price when missing); and output tokens are billed at the output price. All prices are per million tokens. Reasoning tokens may be shown for reference, but they are part of the output charge and are not billed separately.
* **Totals and reports** – Daily, monthly, and session views display per-model breakdowns, overall totals, and optional JSON for automation.

Reports are reconstructed from retained local logs. Missing compaction usage records cannot be recovered from their markers alone, and local totals can differ from account-wide Codex usage. Pricing aliases such as `gpt-reserve` affect cost estimates, without changing token totals or revealing an unrecorded backend model.

## Environment Variables

| Variable     | Description                                                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `CODEX_HOME` | Override the root directory, or comma-separated directories, containing Codex homes or saved `codex exec --json` JSONL files |
| `LOG_LEVEL`  | Adjust log verbosity (0 silent … 5 trace)                                                                                    |

When Codex emits a model alias, the CLI automatically resolves it through the LiteLLM pricing data when possible. The built-in `gpt-reserve` alias is priced as `gpt-5.6-luna`. Codex logs retain `codex-auto-review` as a routing alias rather than recording its effective model, so ccusage applies a manually curated, best-effort timeline and marks the result with `"isFallback": true`. Based on OpenAI's [July 30, 2026 Auto-review migration announcement](https://community.openai.com/t/announcing-a-major-price-drop-for-5-6-terra-and-luna-and-fast-mode-for-5-6-sol/1388484), records from that date onward resolve to `gpt-5.6-luna`, while records from March 5 through July 29 resolve to `gpt-5.4`. Server-side routing or catalog overrides can still differ from this estimate.

## Speed Pricing

By default, `ccusage codex` uses `--speed auto`. Codex CLI 0.144.0 and later can persist `thread_settings_applied` events in session rollouts. ccusage associates each token event with the most recent recognized setting. `service_tier = "priority"` or legacy `"fast"` is Fast, `"flex"` is Flex, and `"default"` or `"standard"` is Standard. This supports sessions that switch modes over time instead of applying one multiplier to the entire day or session.

Some usage remains unclassified, including older rollouts, saved headless `codex exec --json` output, and startup usage before the first persisted settings event. For only that unclassified portion, auto mode reads `config.toml` from each `CODEX_HOME` root and uses Fast when any root has `service_tier = "priority"` or legacy `service_tier = "fast"`. If no root requests Fast and a root requests `service_tier = "flex"`, it uses Flex. Otherwise it uses Standard. An unsupported recorded tier is also left unclassified rather than inheriting a stale tier. Explicit `--speed standard`, `--speed flex`, and `--speed fast` override all recorded and fallback tiers.

Fallback detection reads the top-level `service_tier` and lets a named profile override it only when `profile = "name"` selects that profile in `config.toml`. Inactive profiles are ignored, and a selected profile without its own tier inherits the top-level setting. If Codex selected a profile through `--profile` or another configuration file, use an explicit `--speed` for unclassified usage because ccusage cannot infer that selection from `config.toml`.

Fast and Flex pricing use model-specific multipliers only when one is published. GPT-5.6 Sol, Terra, and Luna use the [documented 2× API Priority rate](https://learn.chatgpt.com/docs/agent-configuration/speed#fast-mode), and GPT-6 [Astra](https://developers.openai.com/api/docs/models/gpt-6-astra), [Sol](https://developers.openai.com/api/docs/models/gpt-6-sol), and [Luna](https://developers.openai.com/api/docs/models/gpt-6-luna) and [GPT-6.1 Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol) use their documented 2× Fast rates. Models listed in OpenAI's [Flex pricing table](https://developers.openai.com/api/docs/pricing) use 0.5× Standard pricing, including dated and provider-qualified names. These are distinct from ChatGPT credit-consumption rates. ccusage's `costUSD` is an API-equivalent estimate, not a ChatGPT credit balance. When a model's Fast or Flex rate is unknown, ccusage reports standard pricing rather than assuming a multiplier, which may underestimate Fast usage or overestimate Flex usage.

Use [`pricingOverrides`](/guide/config-files#pricing-overrides) to configure a model's `fastMultiplier` or `flexMultiplier`.

```bash
# Default: use recorded tiers, then config.toml for unmarked usage
ccusage codex daily --speed auto

# Force fast pricing
ccusage codex daily --speed fast

# Force Flex pricing
ccusage codex daily --speed flex

# Force standard pricing
ccusage codex daily --speed standard
```

## JSON Output

Codex focused views use the same JSON mode as the shared reports:

```bash
ccusage codex daily --json
ccusage codex monthly --json
ccusage codex session --json
```

Session JSON includes per-model breakdowns, cached token counts, `lastActivity`, and `isFallback` flags for events that required either the legacy `gpt-5` pricing fallback or the manually curated `codex-auto-review` timeline.

Have feedback or ideas? [Open an issue](https://github.com/ccusage/ccusage/issues/new) so we can improve Codex support.

## Troubleshooting

::: details Why are there no entries before September 2025?
OpenAI's Codex CLI started emitting `token_count` events in [commit 0269096](https://github.com/openai/codex/commit/0269096229e8c8bd95185173706807dc10838c7a) (2025-09-06). Earlier session logs simply don't contain token usage metrics, so `ccusage codex` has nothing to aggregate. If you need historic data, rerun those sessions after that Codex update.
:::

::: details What if some September 2025 sessions still get skipped?
During the 2025-09 rollouts a few Codex builds emitted `token_count` events without the matching `turn_context` metadata, so the CLI could not determine which model generated the tokens. Those entries are ignored to avoid mispriced reports. If you encounter this, relaunch the Codex CLI to generate fresh logs—the current builds restore the missing metadata.
:::

---

---
url: /guide/opencode.md
---
# OpenCode Data Source (Beta)

> OpenCode support is experimental. Expect breaking changes while both ccusage and [OpenCode](https://github.com/opencode-ai/opencode) continue to evolve.

ccusage can read [OpenCode](https://github.com/opencode-ai/opencode) session logs as one of its supported local data sources. OpenCode is a terminal-based AI coding assistant that supports multiple AI providers.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage opencode --help
```

```bash [npx]
npx ccusage@latest opencode --help
```

```bash [pnpm]
pnpm dlx ccusage opencode --help
```

```bash [opencode x]
BUN_BE_BUN=1 opencode x ccusage@latest opencode --help
```

:::

::: tip opencode x option
The `opencode x` option requires the native version of OpenCode. If you installed OpenCode via npm, use the `bunx` or `npx` options instead.
:::

## Data Source

The CLI reads OpenCode message and session JSON files from `OPENCODE_DATA_DIR` when it is set. Otherwise, it uses `${XDG_DATA_HOME:-$HOME/.local/share}/opencode`. `OPENCODE_DATA_DIR` can be one directory or a comma-separated list of directories.

```bash
OPENCODE_DATA_DIR="$HOME/.local/share/opencode,/backup/opencode" ccusage opencode daily
```

```
${XDG_DATA_HOME:-$HOME/.local/share}/opencode/
└── storage/
    ├── message/{sessionID}/msg_{messageID}.json
    └── session/{projectHash}/{sessionID}.json
```

## Report Views

| Focused view               | Description                                          | See also                                |
| -------------------------- | ---------------------------------------------------- | --------------------------------------- |
| `ccusage opencode daily`   | Aggregate usage by date (YYYY-MM-DD)                 | [Daily Usage](/guide/daily-reports)     |
| `ccusage opencode weekly`  | Aggregate usage by ISO week (YYYY-Www)               | [Weekly Usage](/guide/weekly-reports)   |
| `ccusage opencode monthly` | Aggregate usage by month (YYYY-MM)                   | [Monthly Usage](/guide/monthly-reports) |
| `ccusage opencode session` | Per-session breakdown with parent/subagent hierarchy | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output and `--compact` for narrow terminals. See the linked ccusage documentation for detailed flag descriptions.

## Session Hierarchy

OpenCode supports subagent sessions. The session report displays:

* **Bold titles** for parent sessions with subagents
* **Indented rows** (`↳`) for subagent sessions
* **Subtotal rows** combining parent + subagents

## Forked Sessions

When OpenCode v2 forks a session, it copies the parent's history into the fork. ccusage counts only the usage the fork generates itself, so copied turns are not counted twice in session, daily, weekly, or monthly reports. If the fork's parent session or boundary message is no longer in the database, the fork keeps all of its rows.

## Environment Variables

| Variable            | Description                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `OPENCODE_DATA_DIR` | Override the root directory, or comma-separated root directories, containing OpenCode data |
| `XDG_DATA_HOME`     | Base directory for OpenCode data when `OPENCODE_DATA_DIR` is not set                       |
| `LOG_LEVEL`         | Adjust verbosity (0 silent ... 5 trace)                                                    |

## Cost Calculation

OpenCode stores `cost: 0` in message files. Costs are calculated from token counts using LiteLLM pricing. Model aliases (e.g., `gemini-3-pro-high` → `gemini-3-pro-preview`) are handled automatically.

## Troubleshooting

::: details No OpenCode usage data found
Ensure the data directory exists at `${XDG_DATA_HOME:-$HOME/.local/share}/opencode/storage/message/`. Set `OPENCODE_DATA_DIR` for custom paths or comma-separated archive roots.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/amp.md
---
# Amp Data Source (Beta)

> Amp support is experimental. Expect breaking changes while both ccusage and [Amp](https://ampcode.com/) continue to evolve.

ccusage can read Amp thread files as one of its supported local data sources, using the same reporting experience as the rest of ccusage: responsive tables, JSON output, LiteLLM-based pricing, cache token accounting, and credit totals where Amp records them.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage amp --help
```

```bash [npx]
npx ccusage@latest amp --help
```

```bash [pnpm]
pnpm dlx ccusage amp --help
```

:::

## Data Source

The CLI reads Amp thread JSON files from `AMP_DATA_DIR` (defaults to `~/.local/share/amp`). `AMP_DATA_DIR` can be one directory or a comma-separated list of directories.

```bash
AMP_DATA_DIR="$HOME/.local/share/amp,/backup/amp" ccusage amp session
```

```text
~/.local/share/amp/
└── threads/
    └── **/*.json
```

## Report Views

| Focused view          | Description               | See also                                |
| --------------------- | ------------------------- | --------------------------------------- |
| `ccusage amp daily`   | Aggregate usage by date   | [Daily Usage](/guide/daily-reports)     |
| `ccusage amp monthly` | Aggregate usage by month  | [Monthly Usage](/guide/monthly-reports) |
| `ccusage amp session` | Group usage by Amp thread | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output, `--compact` for narrow terminals, and `--offline` for cached pricing data.

## What Gets Calculated

* **Token usage** - Amp usage ledger events provide input and output token counts.
* **Cache tokens** - Assistant message usage fields provide cache creation and cache read tokens when available.
* **Credits** - Amp credit values are summed alongside token and cost totals.
* **Pricing** - Costs are calculated from LiteLLM pricing data for Claude and Anthropic model names, including provider-prefixed variants.

## Environment Variables

| Variable       | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `AMP_DATA_DIR` | Override the root directory, or comma-separated root directories, containing Amp data |
| `LOG_LEVEL`    | Adjust verbosity (0 silent ... 5 trace)                                               |

## Troubleshooting

::: details No Amp usage data found
Ensure the data directory exists at `~/.local/share/amp/threads/`. Set `AMP_DATA_DIR` if your Amp data lives elsewhere or in multiple archive roots.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/droid.md
---
# Droid Data Source (Experimental)

> Droid support is experimental. Expect breaking changes while both ccusage and Droid continue to evolve.

ccusage can read local Droid session settings files as one of its supported data sources, using the same daily, monthly, and session report views as the rest of ccusage.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage droid --help
```

```bash [npx]
npx ccusage@latest droid --help
```

```bash [pnpm]
pnpm dlx ccusage droid --help
```

:::

## Data Source

The CLI reads Droid settings JSON files from `DROID_SESSIONS_DIR` (defaults to `~/.factory/sessions`). `DROID_SESSIONS_DIR` can be one directory or a comma-separated list of directories.

```bash
DROID_SESSIONS_DIR="$HOME/.factory/sessions,/backup/factory/sessions" ccusage droid session
```

```text
~/.factory/sessions/
└── **/*.settings.json
```

## Report Views

| Focused view            | Description                  | See also                                |
| ----------------------- | ---------------------------- | --------------------------------------- |
| `ccusage droid daily`   | Aggregate usage by date      | [Daily Usage](/guide/daily-reports)     |
| `ccusage droid monthly` | Aggregate usage by month     | [Monthly Usage](/guide/monthly-reports) |
| `ccusage droid session` | Group usage by Droid session | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output, `--compact` for narrow terminals, and `--offline` for cached pricing data.

## What Gets Calculated

* **Token usage** - Droid settings files provide input, output, cache creation, cache read, and thinking token counts.
* **Reasoning tokens** - Thinking tokens are included in total tokens and output-side cost estimation.
* **Pricing** - Costs are calculated from LiteLLM pricing data for the recorded model and provider.

## Environment Variables

| Variable             | Description                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `DROID_SESSIONS_DIR` | Override the sessions directory, or comma-separated sessions directories, containing Droid data |
| `LOG_LEVEL`          | Adjust verbosity (0 silent ... 5 trace)                                                         |

## Troubleshooting

::: details No Droid usage data found
Ensure the data directory exists at `~/.factory/sessions/` and contains `*.settings.json` files. Set `DROID_SESSIONS_DIR` if your Droid data lives elsewhere or in multiple archive roots.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/codebuff.md
---
# Codebuff Data Source (Experimental)

> Codebuff support is experimental. Expect adjustments while the local data format continues to evolve.

ccusage can read Codebuff chat history files as one of its supported local data sources, using the same reporting experience as the rest of ccusage: responsive tables, JSON output, LiteLLM-based pricing, cache token accounting, and credit totals where Codebuff records them.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage codebuff --help
```

```bash [npx]
npx ccusage@latest codebuff --help
```

```bash [pnpm]
pnpm dlx ccusage codebuff --help
```

:::

## Data Source

The CLI reads Codebuff chat JSON files from `CODEBUFF_DATA_DIR`. Set `CODEBUFF_DATA_DIR` to one channel root or a comma-separated list of channel roots when your data lives outside the standard locations.

When `CODEBUFF_DATA_DIR` is not set, ccusage checks the stable, dev, and staging channel roots:

```text
~/.config/manicode/
~/.config/manicode-dev/
~/.config/manicode-staging/
```

Each root is expected to contain project chat histories:

```text
~/.config/manicode/
└── projects/
    └── <project>/
        └── chats/
            └── <chat-id>/
                └── chat-messages.json
```

Use a custom root when your Codebuff data lives elsewhere:

```bash
CODEBUFF_DATA_DIR="$HOME/.config/manicode,/backup/codebuff" ccusage codebuff session
```

## Report Views

| Focused view               | Description                          | See also                                |
| -------------------------- | ------------------------------------ | --------------------------------------- |
| `ccusage codebuff daily`   | Aggregate usage by date              | [Daily Usage](/guide/daily-reports)     |
| `ccusage codebuff monthly` | Aggregate usage by month             | [Monthly Usage](/guide/monthly-reports) |
| `ccusage codebuff session` | Group usage by Codebuff chat session | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output, `--compact` for narrow terminals, and `--offline` for cached pricing data.

## What Gets Calculated

* **Token usage** - Assistant messages can provide input and output token counts from `metadata.usage`, `metadata.codebuff.usage`, or nested run-state provider usage.
* **Cache tokens** - Cache creation and cache read tokens are included when the Codebuff message metadata records them.
* **Credits** - Codebuff credit values are summed in row metadata and included in per-agent JSON output.
* **Pricing** - Costs are estimated from LiteLLM pricing data for Anthropic, OpenAI, Google, xAI, and provider-prefixed model names.

## Environment Variables

| Variable            | Description                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `CODEBUFF_DATA_DIR` | Override the channel root, or comma-separated channel roots, containing Codebuff projects |
| `LOG_LEVEL`         | Adjust verbosity (0 silent ... 5 trace)                                                   |

## Troubleshooting

::: details No Codebuff usage data found
Ensure the data directory contains `projects/<project>/chats/<chat-id>/chat-messages.json`. Set `CODEBUFF_DATA_DIR` if your Codebuff data lives outside `~/.config/manicode`, `~/.config/manicode-dev`, or `~/.config/manicode-staging`.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. Costs can also be $0.00 in offline mode when pricing data is unavailable. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/hermes.md
---
# Hermes Agent Data Source (Experimental)

> Hermes Agent support is experimental. Expect changes while both ccusage and [Hermes Agent](https://github.com/NousResearch/hermes-agent) continue to evolve.

ccusage can read Hermes Agent session usage from its local SQLite state database. The adapter uses the same focused and unified report shape as the other local coding CLI data sources.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage hermes --help
```

```bash [npx]
npx ccusage@latest hermes --help
```

```bash [pnpm]
pnpm dlx ccusage hermes --help
```

:::

## Data Source

The CLI reads Hermes Agent session rows from `$HERMES_HOME/state.db`. When `HERMES_HOME` is not set, ccusage checks `~/.hermes/state.db`.

```bash
HERMES_HOME="$HOME/.hermes" ccusage hermes daily
```

```text
~/.hermes/
└── state.db
```

## Report Views

| Focused view             | Description                      | See also                                |
| ------------------------ | -------------------------------- | --------------------------------------- |
| `ccusage hermes daily`   | Aggregate usage by date          | [Daily Usage](/guide/daily-reports)     |
| `ccusage hermes monthly` | Aggregate usage by month         | [Monthly Usage](/guide/monthly-reports) |
| `ccusage hermes session` | Group usage by Hermes session ID | [Session Usage](/guide/session-reports) |

These views support `--json`, `--compact`, `--offline`, `--since`, `--until`, and `--timezone`.

## What Gets Calculated

* **Token usage** - Reads input, output, cache read, cache write, and reasoning token totals from Hermes session rows.
* **Total tokens** - Includes reasoning tokens in the total token count.
* **Costs** - Prefers recorded actual cost, then recorded estimated cost, then calculates from LiteLLM pricing when token data is available.
* **Message count** - Preserves Hermes `message_count` in JSON metadata.

## Environment Variables

| Variable      | Description                                                                       |
| ------------- | --------------------------------------------------------------------------------- |
| `HERMES_HOME` | Override the directory containing `state.db`; comma-separated roots are supported |
| `LOG_LEVEL`   | Adjust verbosity (0 silent ... 5 trace)                                           |

## Troubleshooting

::: details No Hermes Agent usage data found
Ensure the database exists at `$HERMES_HOME/state.db` or `~/.hermes/state.db`. If your database lives elsewhere, set `HERMES_HOME` to the directory that contains `state.db`.
:::

::: details Costs showing as $0.00
If Hermes has no recorded cost and a model is not in LiteLLM or ccusage's bundled fallback pricing, the calculated cost will be $0.00.
:::

---

---
url: /guide/pi.md
---
# pi-agent Data Source (Beta)

ccusage can read [pi-agent](https://github.com/badlogic/pi-mono) usage data as one of its supported local data sources. pi-agent is an alternative Claude coding (agent) CLI from [shittycodingagent.ai](https://shittycodingagent.ai).

## What is Pi-Agent?

Pi-agent is a third-party Claude coding (agent) CLI that stores usage data in JSONL format. ccusage analyzes this data alongside its other supported sources.

## Focused Views

```bash
# Recommended
bunx ccusage pi --help

# Alternative package runners
npx ccusage@latest pi --help
pnpm dlx ccusage pi --help
pnpx ccusage pi --help
```

## Data Source

The CLI reads usage data from pi-agent:

| Source   | Default path            | Override                      |
| -------- | ----------------------- | ----------------------------- |
| pi-agent | `~/.pi/agent/sessions/` | `PI_AGENT_DIR` or `--pi-path` |

Both `PI_AGENT_DIR` and `--pi-path` can be one sessions directory or a comma-separated list of sessions directories.

Tools built on the pi session format can also be declared as named stores in the config file for unified reports:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"pi": {
		"stores": [
			{
				"name": "omp",
				"path": "~/.omp/agent/sessions"
			}
		]
	}
}
```

Named stores are loaded in addition to the default `pi` agent when running `ccusage daily`, `ccusage monthly`, `ccusage weekly`, or `ccusage session`. The example above appears as agent `omp` in unified report metadata and prefixes model labels with `[omp]` followed by a space. A named store path can also be a comma-separated list of sessions directories; missing paths are treated as empty, while paths that overlap the default `pi` store or another named store — including one path nested inside another — are rejected to avoid double-counting. It does not add a `ccusage omp` command; use `ccusage pi ...` for the default pi-agent store.

For custom Pi models, add a [`pricingOverrides` entry](/guide/config-files#pricing-overrides) keyed by the model label, such as `[pi] my-custom-model` or `[omp] my-custom-model` for a named store. In the default `auto` mode, an explicit override calculates cost from tokens even when Pi recorded a zero cost. Use `--mode display` to show Pi's recorded cost instead.

## Report Views

```bash
# Show daily pi-agent usage
ccusage pi daily

# Show monthly pi-agent usage
ccusage pi monthly

# Show session-based pi-agent usage
ccusage pi session

# JSON output for automation
ccusage pi daily --json

# Custom pi-agent path
ccusage pi daily --pi-path /path/to/sessions

# Multiple pi-agent paths
ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions

# Filter by date range
ccusage pi daily --since 2026-05-01 --until 2026-05-16

# Show model breakdown
ccusage pi daily --breakdown
```

## Environment Variables

| Variable       | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `PI_AGENT_DIR` | Custom path, or comma-separated paths, to pi-agent sessions directories |
| `LOG_LEVEL`    | Adjust logging verbosity (0 silent … 5 trace)                           |

## Daily View

This view shows daily usage from pi-agent.

```bash
# Recommended (fastest)
bunx ccusage pi daily

# Using npx
npx ccusage@latest pi daily
```

### Options

| Flag          | Short | Description                                                             |
| ------------- | ----- | ----------------------------------------------------------------------- |
| `--since`     |       | Start date filter (YYYY-MM-DD or YYYYMMDD)                              |
| `--until`     |       | End date filter (YYYY-MM-DD or YYYYMMDD)                                |
| `--timezone`  | `-z`  | Override timezone for date grouping                                     |
| `--json`      |       | Emit structured JSON instead of a table                                 |
| `--breakdown` | `-b`  | Show per-model token breakdown                                          |
| `--pi-path`   |       | Custom path, or comma-separated paths, to pi-agent sessions directories |
| `--order`     |       | Sort order: `asc` or `desc` (default: `desc`)                           |

### Example Output

```
┌────────────┬────────────┬─────────────┬───────────┬───────────┬────────┬─────────┐
│ Date       │ Input      │ Output      │ Cache Cr. │ Cache Rd. │ Cost   │ Models  │
├────────────┼────────────┼─────────────┼───────────┼───────────┼────────┼─────────┤
│ 2026-05-16 │ 567,890    │ 123,456     │ 5,678     │ 45,678    │ $0.89  │ opus-4-1  │
├────────────┼────────────┼─────────────┼───────────┼───────────┼────────┼─────────┤
│ Total      │ 567,890    │ 123,456     │ 5,678     │ 45,678    │ $0.89  │         │
└────────────┴────────────┴─────────────┴───────────┴───────────┴────────┴─────────┘
```

### JSON Output

Use `--json` for automation and scripting:

```bash
ccusage pi daily --json
```

Returns structured data:

```json
{
  "daily": [
    {
      "date": "2026-05-16",
      "source": "pi-agent",
      "inputTokens": 567890,
      "outputTokens": 123456,
      "cacheCreationTokens": 5678,
      "cacheReadTokens": 45678,
      "totalCost": 0.89,
      "modelsUsed": ["claude-opus-4-1-20250805"],
      "modelBreakdowns": [...]
    }
  ],
  "totals": {
    "inputTokens": 567890,
    "outputTokens": 123456,
    "cacheCreationTokens": 5678,
    "cacheReadTokens": 45678,
    "totalCost": 0.89
  }
}
```

### Date Filtering

Filter to a specific date range:

```bash
# Last week
ccusage pi daily --since 2026-05-09 --until 2026-05-16

# Single day
ccusage pi daily --since 2026-05-16 --until 2026-05-16
```

## Monthly View

This view shows monthly usage from pi-agent.

```bash
# Recommended (fastest)
bunx ccusage pi monthly

# Using npx
npx ccusage@latest pi monthly
```

### Options

| Flag          | Short | Description                                                             |
| ------------- | ----- | ----------------------------------------------------------------------- |
| `--since`     |       | Start date filter (YYYY-MM-DD or YYYYMMDD)                              |
| `--until`     |       | End date filter (YYYY-MM-DD or YYYYMMDD)                                |
| `--timezone`  | `-z`  | Override timezone for date grouping                                     |
| `--json`      |       | Emit structured JSON instead of a table                                 |
| `--breakdown` | `-b`  | Show per-model token breakdown                                          |
| `--pi-path`   |       | Custom path, or comma-separated paths, to pi-agent sessions directories |
| `--order`     |       | Sort order: `asc` or `desc` (default: `desc`)                           |

### Example Output

```
┌─────────┬────────────┬─────────────┬───────────┬───────────┬─────────┬─────────┐
│ Month   │ Input      │ Output      │ Cache Cr. │ Cache Rd. │ Cost    │ Models  │
├─────────┼────────────┼─────────────┼───────────┼───────────┼─────────┼─────────┤
│ 2026-05 │ 12,345,678 │ 2,345,678   │ 123,456   │ 987,654   │ $12.34  │ opus-4-1  │
├─────────┼────────────┼─────────────┼───────────┼───────────┼─────────┼─────────┤
│ Total   │ 12,345,678 │ 2,345,678   │ 123,456   │ 987,654   │ $12.34  │         │
└─────────┴────────────┴─────────────┴───────────┴───────────┴─────────┴─────────┘
```

### JSON Output

Use `--json` for automation and scripting:

```bash
ccusage pi monthly --json
```

Returns structured data:

```json
{
  "monthly": [
    {
      "month": "2026-05",
      "source": "pi-agent",
      "inputTokens": 12345678,
      "outputTokens": 2345678,
      "cacheCreationTokens": 123456,
      "cacheReadTokens": 987654,
      "totalCost": 12.34,
      "modelsUsed": ["claude-opus-4-1-20250805"],
      "modelBreakdowns": [...]
    }
  ],
  "totals": {
    "inputTokens": 12345678,
    "outputTokens": 2345678,
    "cacheCreationTokens": 123456,
    "cacheReadTokens": 987654,
    "totalCost": 12.34
  }
}
```

### Filtering by Date Range

You can filter the data to specific months:

```bash
# Current year only
ccusage pi monthly --since 2026-05-01

# Specific quarter
ccusage pi monthly --since 2026-01-01 --until 2026-03-31
```

## Session View

This view shows usage grouped by individual pi-agent sessions.

```bash
# Recommended (fastest)
bunx ccusage pi session

# Using npx
npx ccusage@latest pi session
```

### Options

| Flag          | Short | Description                                                             |
| ------------- | ----- | ----------------------------------------------------------------------- |
| `--since`     |       | Start date filter (YYYY-MM-DD or YYYYMMDD)                              |
| `--until`     |       | End date filter (YYYY-MM-DD or YYYYMMDD)                                |
| `--timezone`  | `-z`  | Override timezone for date grouping                                     |
| `--json`      |       | Emit structured JSON instead of a table                                 |
| `--breakdown` | `-b`  | Show per-model token breakdown                                          |
| `--pi-path`   |       | Custom path, or comma-separated paths, to pi-agent sessions directories |
| `--order`     |       | Sort order: `asc` or `desc` (default: `desc`)                           |

### Example Output

Sessions are sorted by last activity:

```
┌──────────────────────────────┬────────────┬───────────┬───────────┬───────────┬────────┬─────────┐
│ Session                      │ Input      │ Output    │ Cache Cr. │ Cache Rd. │ Cost   │ Models  │
├──────────────────────────────┼────────────┼───────────┼───────────┼───────────┼────────┼─────────┤
│ my-project                   │ 123,456    │ 23,456    │ 1,234     │ 9,876     │ $0.12  │ opus-4-1  │
│ another-repo                 │ 345,678    │ 67,890    │ 3,456     │ 29,876    │ $0.34  │ sonnet-4-5│
├──────────────────────────────┼────────────┼───────────┼───────────┼───────────┼────────┼─────────┤
│ Total                        │ 469,134    │ 91,346    │ 4,690     │ 39,752    │ $0.46  │         │
└──────────────────────────────┴────────────┴───────────┴───────────┴───────────┴────────┴─────────┘
```

### Session Identification

Sessions are identified by the project folder name from `~/.pi/agent/sessions/{project}/`.

Long project names are truncated to 25 characters with `...` suffix for readability.

### JSON Output

Use `--json` for detailed session data:

```bash
ccusage pi session --json
```

Returns structured data including full paths:

```json
{
  "sessions": [
    {
      "sessionId": "abc123-def456",
      "projectPath": "my-project",
      "source": "pi-agent",
      "inputTokens": 123456,
      "outputTokens": 23456,
      "cacheCreationTokens": 1234,
      "cacheReadTokens": 9876,
      "totalCost": 0.12,
      "firstActivity": "2026-05-15T09:30:00.000Z",
      "lastActivity": "2026-05-16T17:45:30.000Z",
      "modelsUsed": ["claude-opus-4-1-20250805"],
      "modelBreakdowns": [...]
    }
  ],
  "totals": {
    "inputTokens": 123456,
    "outputTokens": 23456,
    "cacheCreationTokens": 1234,
    "cacheReadTokens": 9876,
    "totalCost": 0.12
  }
}
```

### Filtering Sessions

Filter sessions by their last activity date:

```bash
# Sessions active today
ccusage pi session --since 2026-05-16 --until 2026-05-16

# Sessions from the past week
ccusage pi session --since 2026-05-09
```

## Related

* [ccusage](https://github.com/ccusage/ccusage) - Main usage analysis tool for coding (agent) CLIs
* [pi-agent](https://github.com/badlogic/pi-mono) - Alternative Claude coding (agent) CLI

---

---
url: /guide/goose.md
---
# Goose Data Source (Experimental)

Goose support is experimental. ccusage can read Goose session usage from its local SQLite database. Goose is a local AI agent, and ccusage only opens the database read-only.

## Quick Start

```bash
ccusage goose daily
ccusage goose monthly
ccusage goose session
```

Goose is also included in unified reports when a supported database is detected:

```bash
ccusage daily
```

## Data Locations

By default, ccusage checks these Goose database locations:

```text
~/.local/share/goose/sessions/sessions.db
~/Library/Application Support/goose/sessions/sessions.db
~/.local/share/Block/goose/sessions/sessions.db
```

Set `GOOSE_PATH_ROOT` when Goose is stored somewhere else:

```bash
GOOSE_PATH_ROOT="/path/to/goose" ccusage goose daily
```

With `GOOSE_PATH_ROOT` set, ccusage reads:

```text
$GOOSE_PATH_ROOT/data/sessions/sessions.db
```

## Token Mapping

ccusage reads Goose session rows with model configuration and token columns:

| Goose column                                        | ccusage field       |
| --------------------------------------------------- | ------------------- |
| `accumulated_input_tokens` or `input_tokens`        | Input tokens        |
| `accumulated_output_tokens` or `output_tokens`      | Output tokens       |
| `accumulated_total_tokens` or `total_tokens`        | Total tokens        |
| `total - input - output`, when positive             | Reasoning/extra use |
| `model_config_json.model_name`                      | Model               |
| `provider_name`, when present, otherwise model hint | Provider            |

Goose does not expose cache read/write token columns in this database, so cache columns are reported as zero.

## Cost Calculation

Goose rows do not store recorded USD cost, so ccusage estimates cost from token counts and LiteLLM pricing. Any positive total-token remainder beyond input and output is treated as output-priced usage for cost estimation.

Use `--offline` to rely on cached pricing data:

```bash
ccusage goose daily --offline
```

## Troubleshooting

If no Goose data appears, check that the SQLite database exists at one of the default paths or set `GOOSE_PATH_ROOT`.

```bash
GOOSE_PATH_ROOT="/path/to/goose" ccusage goose session --json
```

---

---
url: /guide/kilo.md
---
# Kilo Data Source (Beta)

ccusage can read Kilo CLI usage data as one of its supported local data sources. Kilo stores local session data in a SQLite database with model, token, cache, and cost fields.

## Focused Views

```bash
# Recommended
bunx ccusage kilo --help

# Alternative package runners
npx ccusage@latest kilo --help
pnpm dlx ccusage kilo --help
pnpx ccusage kilo --help
```

## Data Source

The CLI reads Kilo messages from `KILO_DATA_DIR` (defaults to `~/.local/share/kilo`). `KILO_DATA_DIR` can be one directory or a comma-separated list of directories.

```bash
KILO_DATA_DIR="$HOME/.local/share/kilo,/backup/kilo" ccusage kilo daily
```

```text
~/.local/share/kilo/
└── kilo.db
```

## Report Views

| Focused view           | Description                          | See also                                |
| ---------------------- | ------------------------------------ | --------------------------------------- |
| `ccusage kilo daily`   | Aggregate usage by date (YYYY-MM-DD) | [Daily Usage](/guide/daily-reports)     |
| `ccusage kilo monthly` | Aggregate usage by month (YYYY-MM)   | [Monthly Usage](/guide/monthly-reports) |
| `ccusage kilo session` | Per-session breakdown                | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output and `--compact` for narrow terminals. See the linked ccusage documentation for detailed flag descriptions.

## Environment Variables

| Variable        | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `KILO_DATA_DIR` | Override the root directory, or comma-separated root directories, containing Kilo data |
| `LOG_LEVEL`     | Adjust verbosity (0 silent ... 5 trace)                                                |

## Cost Calculation

When Kilo records a cost (including `0`), ccusage uses that value. Otherwise, costs are calculated from token counts using LiteLLM pricing.

## Troubleshooting

::: details No Kilo usage data found
Ensure the data directory exists at `~/.local/share/kilo/` and contains `kilo.db`. Set `KILO_DATA_DIR` for custom paths or comma-separated archive roots.
:::

::: details Costs showing as $0.00
If Kilo did not record a cost and the model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/qwen.md
---
# Qwen Data Source (Experimental)

> Qwen support is experimental. Expect breaking changes while both ccusage and [Qwen Code](https://github.com/QwenLM/qwen-code) continue to evolve.

ccusage can read Qwen Code chat JSONL files as one of its supported local data sources, using the same focused and all-source report views as the rest of ccusage.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage qwen --help
```

```bash [npx]
npx ccusage@latest qwen --help
```

```bash [pnpm]
pnpm dlx ccusage qwen --help
```

:::

## Data Source

The CLI reads Qwen chat JSONL files from `QWEN_DATA_DIR` (defaults to `~/.qwen`). `QWEN_DATA_DIR` can be one directory or a comma-separated list of directories.

```bash
QWEN_DATA_DIR="$HOME/.qwen,/backup/qwen" ccusage qwen daily
```

```text
~/.qwen/
└── projects/
    └── {project}/
        └── chats/
            └── *.jsonl
```

## Report Views

| Focused view           | Description                 | See also                                |
| ---------------------- | --------------------------- | --------------------------------------- |
| `ccusage qwen daily`   | Aggregate usage by date     | [Daily Usage](/guide/daily-reports)     |
| `ccusage qwen monthly` | Aggregate usage by month    | [Monthly Usage](/guide/monthly-reports) |
| `ccusage qwen session` | Group usage by Qwen session | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output, `--compact` for narrow terminals, and `--offline` for cached pricing data.

## What Gets Calculated

* **Token usage** - Qwen assistant rows provide input and output token counts through `usageMetadata`.
* **Reasoning tokens** - `thoughtsTokenCount` is included in `totalTokens` and priced as output tokens when pricing data is available.
* **Cache tokens** - `cachedContentTokenCount` is treated as cache read tokens. Qwen logs do not currently expose cache creation tokens.
* **Pricing** - Costs are calculated from LiteLLM pricing data using the raw model name and Qwen provider-prefixed candidates.

## Environment Variables

| Variable        | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `QWEN_DATA_DIR` | Override the root directory, or comma-separated root directories, containing Qwen data |
| `LOG_LEVEL`     | Adjust verbosity (0 silent ... 5 trace)                                                |

## Troubleshooting

::: details No Qwen usage data found
Ensure the data directory exists at `~/.qwen/projects/{project}/chats/`. Set `QWEN_DATA_DIR` if your Qwen data lives elsewhere or in multiple archive roots.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/copilot.md
---
# GitHub Copilot CLI Data Source (Beta)

> GitHub Copilot CLI support is experimental. The adapter reads local session-state and OpenTelemetry JSONL files.

ccusage can read GitHub Copilot CLI session-state and OpenTelemetry files as supported local data sources. It uses the same reporting experience as the rest of ccusage: responsive tables, JSON output, LiteLLM-based pricing, cache token accounting, and all-source aggregation.

## Focused Views

::: code-group

```bash [bunx (Recommended)]
bunx ccusage copilot --help
```

```bash [npx]
npx ccusage@latest copilot --help
```

```bash [pnpm]
pnpm dlx ccusage copilot --help
```

:::

## Data Source

The CLI reads Copilot session-state shutdown and usage-checkpoint events from `${COPILOT_HOME:-~/.copilot}/session-state/*/events.jsonl` by default. It also reads OpenTelemetry JSONL files recursively from `${COPILOT_HOME:-~/.copilot}/otel/**/*.jsonl` and includes the single explicit file pointed to by `COPILOT_OTEL_FILE_EXPORTER_PATH`. Set `COPILOT_HOME` to the Copilot data root when the default `~/.copilot` directory has been relocated.

Session-state files do not require OpenTelemetry configuration. Shutdown usage is cumulative per canonical session/model pair, and resumed sessions emit another shutdown snapshot. ccusage reports the first snapshot as-is and each later snapshot as the difference from its predecessor, so usage follows the resume dates while totals stay unchanged. For date-bounded reports, snapshots before `--since` remain available as subtraction baselines, and snapshots after `--until` are excluded. When both sources contain the same session/model pair, the session-state usage is used and matching OpenTelemetry rows are suppressed only when their timestamps are at or before the latest raw shutdown visible through `--until`; rows emitted after that timestamp by a resumed session are retained. A Copilot process restores the per-model breakdown of the session's last shutdown, so the calls of a process that ended without a shutdown (killed, crashed, or restarted by the app) are missing from every later one. When the OpenTelemetry rows of a pair outnumber the requests its shutdowns report, counted from the first shutdown interval that has OpenTelemetry rows, ccusage reports those rows instead of the shutdown intervals from that interval on. This comparison covers every shutdown, so a date-bounded report shows the same usage per day as an unbounded one. OpenTelemetry rows for other session/model pairs remain available. Chat spans that the CLI exports twice, with the response ID and usage of the same call, are counted once.

For session-state token usage, only `session.shutdown` events are used. For each `data.modelMetrics.<model>` entry, ccusage reads its `usage` fields and uses any positive `requests.count` for `messageCount`; each retained OpenTelemetry usage row contributes one message. `requests.cost` is ignored and costs continue to use ccusage's normal token pricing. In session-state data, `inputTokens` includes both cache buckets, so ccusage derives uncached input as `max(inputTokens - cacheReadTokens - cacheWriteTokens, 0)` before populating `inputTokens`; cache reads and cache writes are then reported separately. OpenTelemetry `gen_ai.usage.input_tokens` includes both cache buckets as well and is normalized the same way. `reasoningTokens` is a subset of `outputTokens`, so it is not added again to output, total tokens, or cost. Copilot model IDs with `-1m` or `-1m-internal` suffixes, such as `claude-opus-4.6-1m`, are normalized to their priced model name for pricing and source deduplication.

For example, a `claude-opus-4.7` shutdown with `inputTokens=100`, `outputTokens=50`, `cacheReadTokens=10`, and `cacheWriteTokens=20` is reported as 70 input tokens, 50 output tokens, 20 cache-creation tokens, and 10 cache-read tokens. With the embedded Opus pricing, its calculated cost is exactly `$0.00173`.

Copilot also records the credits a session has used: a session-wide `totalNanoAiu` on every `session.shutdown` and on the `session.usage_checkpoint` events written during the session. One AIU is one GitHub AI credit, billed at $0.01. The per-model breakdown only covers the running Copilot process, so a resumed or restarted session can shut down with an empty or partial `modelMetrics` while its session total still includes everything. ccusage compares the session total with the per-model `totalNanoAiu` values reported so far, at every shutdown and at each checkpoint after a session's last shutdown, which covers sessions that are still open or ended without a shutdown. Credits that stay unexplained at every later snapshot are reported as a cost-only row for the `unknown` model with zero tokens, dated at the first snapshot from which they stay unexplained. A breakdown that a later shutdown catches up on is not counted twice. Sessions without checkpoints, which come from older Copilot versions that restart both totals on every resume, sessions with a shutdown that lacks either credit total, and sessions that also have OpenTelemetry rows keep token-only reporting. These rows carry a precomputed cost, so `--mode calculate` reports them as $0.

Enable these variables before starting or resuming a Copilot CLI session when you want OTel data. Sessions that ran without OpenTelemetry file export remain readable from their session-state files.

```bash
export COPILOT_HOME="$HOME/.copilot"
export COPILOT_OTEL_ENABLED=true
export COPILOT_OTEL_EXPORTER_TYPE=file
mkdir -p "$COPILOT_HOME/otel"
export COPILOT_OTEL_FILE_EXPORTER_PATH="$COPILOT_HOME/otel/copilot-otel-$(date +%Y%m%d-%H%M%S).jsonl"
```

```text
${COPILOT_HOME:-~/.copilot}/
├── session-state/
│   └── <session-id>/
│       └── events.jsonl
└── otel/
    └── *.jsonl
```

## Report Views

| Focused view              | Description                        | See also                                |
| ------------------------- | ---------------------------------- | --------------------------------------- |
| `ccusage copilot daily`   | Aggregate usage by date            | [Daily Usage](/guide/daily-reports)     |
| `ccusage copilot monthly` | Aggregate usage by month           | [Monthly Usage](/guide/monthly-reports) |
| `ccusage copilot session` | Group usage by Copilot session IDs | [Session Usage](/guide/session-reports) |

These views support `--json` for structured output, `--compact` for narrow terminals, and `--offline` for cached pricing data.

## What Gets Calculated

* **Token usage** - cumulative session shutdown snapshots are converted into per-resume intervals, and OTel rows replace them when the shutdowns miss calls; OTel chat spans are preferred within the OTel source, with inference logs and agent-turn logs used as fallbacks.
* **Cache tokens** - cache read and cache creation token attributes are counted when present.
* **Input tokens** - session-state `inputTokens` and OTel `gen_ai.usage.input_tokens` are normalized to uncached input after subtracting cache reads and cache writes.
* **Reasoning tokens** - session-state reasoning tokens are already included in output tokens; OpenTelemetry reasoning is included when total usage metadata shows it is separate.
* **Pricing** - costs are calculated from LiteLLM pricing data using the normalized model name; both `-1m` and `-1m-internal` suffixes are removed.
* **Unattributed credits** - session credits missing from the per-model breakdown are reported as `unknown` rows at $0.01 per AI credit.

## Environment Variables

| Variable                          | Description                                          |
| --------------------------------- | ---------------------------------------------------- |
| `COPILOT_HOME`                    | Copilot data root; defaults to `~/.copilot`          |
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Explicit Copilot OpenTelemetry JSONL file to include |
| `LOG_LEVEL`                       | Adjust verbosity (0 silent ... 5 trace)              |

## Troubleshooting

::: details No Copilot usage data found
Ensure Copilot session-state files exist under `${COPILOT_HOME:-~/.copilot}/session-state/<session-id>/events.jsonl`, or enable OpenTelemetry file export and place exported `.jsonl` files under `${COPILOT_HOME:-~/.copilot}/otel/`.

If you are using `copilot --resume`, session-state events remain available without OpenTelemetry. OTel-only activity from sessions started without file export cannot be recovered by ccusage.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. [Open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/gemini.md
---
# Gemini CLI Data Source (Beta)

> Gemini CLI support is experimental while the Gemini CLI log format continues to evolve.

ccusage can read Gemini CLI chat logs as one of its supported local data sources. Gemini uses the same unified and focused report model as Claude Code, Codex, OpenCode, Amp, pi-agent, and GitHub Copilot CLI.

## Focused Views

```bash
# Daily Gemini CLI usage
ccusage gemini daily

# Monthly Gemini CLI usage
ccusage gemini monthly

# Gemini CLI sessions
ccusage gemini session
```

Most users can start with unified reports such as `ccusage daily`. Add the `gemini` namespace only when you want to focus the same report shape on Gemini CLI usage.

## Data Source

The CLI reads Gemini CLI JSON and JSONL files located under `GEMINI_DATA_DIR` (defaults to `~/.gemini/tmp`). `GEMINI_DATA_DIR` can be one directory or a comma-separated list of directories. Antigravity SQLite conversations are a separate source; see [Antigravity](/guide/antigravity/).

```bash
GEMINI_DATA_DIR="$HOME/.gemini/tmp,/backup/gemini/tmp" ccusage gemini daily
```

```text
~/.gemini/tmp/
└── */
    └── chats/
        ├── *.json
        └── *.jsonl
```

## Report Views

| Focused view             | Description                       | See also                                |
| ------------------------ | --------------------------------- | --------------------------------------- |
| `ccusage gemini daily`   | Aggregate usage by date           | [Daily Usage](/guide/daily-reports)     |
| `ccusage gemini monthly` | Aggregate usage by month          | [Monthly Usage](/guide/monthly-reports) |
| `ccusage gemini session` | Group usage by Gemini CLI session | [Session Usage](/guide/session-reports) |

These views support `--json`, `--compact`, and `--offline`.

## What Gets Calculated

* **Token usage** - Gemini token records provide input, output, cached, thought, tool, and total token counts when available.
* **Cache tokens** - Gemini `input` values can include cached prompt tokens. ccusage separates those cached tokens into cache read so input and cache read are not double-counted.
* **Reasoning tokens** - Gemini `thoughts` tokens are included in total tokens and exposed as `reasoningTokens` in JSON output. They are priced with output tokens.
* **Pricing** - Costs are calculated from LiteLLM pricing data for Gemini, Google, Vertex AI, and OpenRouter Gemini model names.

## Environment Variables

| Variable          | Description                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `GEMINI_DATA_DIR` | Override the root directory, or comma-separated root directories, containing Gemini data |
| `LOG_LEVEL`       | Adjust verbosity (0 silent ... 5 trace)                                                  |

## Troubleshooting

::: details No Gemini CLI usage data found
Ensure Gemini CLI has written chat logs under `~/.gemini/tmp/*/chats/`. Set `GEMINI_DATA_DIR` if your Gemini data lives elsewhere or in multiple archive roots.
:::

::: details Costs showing as $0.00
If a model is not in LiteLLM's database, the cost will be $0.00. Use `--offline=false` to fetch the latest pricing data, or [open an issue](https://github.com/ccusage/ccusage/issues/new) to request alias support.
:::

---

---
url: /guide/antigravity.md
---
# Antigravity Data Source

ccusage reads Antigravity's local SQLite conversation databases as a standalone
source. It uses the `antigravity` namespace, so Antigravity rows remain
separate from Gemini CLI rows in focused and unified reports.

## Focused Views

```bash
# Daily Antigravity usage
ccusage antigravity daily

# Monthly Antigravity usage
ccusage antigravity monthly

# Antigravity sessions
ccusage antigravity session
```

These views support the shared report options, including `--json`,
`--breakdown`, `--mode`, `--offline`, `--since`, and `--until`.

## Data Source

By default, ccusage scans these local conversation roots:

* `~/.gemini/antigravity/conversations/`
* `~/.gemini/antigravity-cli/conversations/`
* `~/.gemini/antigravity-ide/conversations/`
* `~/.gemini/antigravity-backup/conversations/`
* `~/.gemini/antigravity-acp/conversations/`
* `~/.config/antigravity/conversations/`

Each root is independent from Gemini CLI discovery. To use one or more custom
roots, set `ANTIGRAVITY_DATA_DIR` to comma-separated directories. A configured
directory can be either an Antigravity data root containing `conversations/` or
the conversation directory itself:

```bash
ANTIGRAVITY_DATA_DIR="$HOME/.gemini/antigravity-cli,/backup/antigravity" \
  ccusage antigravity daily
```

Only `.db` files are read. ccusage opens them read-only and reads the
`gen_metadata` rows in ascending `idx` order. When present, the real `steps`
schema contributes step and retry usage, and `trajectory_metadata_blob` supplies
the timestamp fallback. SQLite, row-iteration, and protobuf failures are
reported instead of becoming empty or partial reports.

## What Gets Calculated

* **Input tokens** - The fresh-input bucket is reported independently.
* **Cache writes and reads** - Both cache buckets remain separate from uncached input.
* **Output and reasoning** - Total output is split into visible output and
  thinking/reasoning tokens.
* **Model names** - Antigravity display names and known internal aliases are
  normalized to stable model IDs. Effort variants remain visible; for example,
  Gemini 3.8 Flash High is reported as `gemini-3.8-flash-high`.
* **Costs** - `calculate` and `auto` use the pricing catalog when a
  matching model is available. Effort variants use their base model's pricing
  when the catalog does not list a separate variant. Use `--offline` to avoid a
  pricing refresh.

Continuation rows inherit the most recently observed model in their database.
Usage in generation metadata and step metadata is combined, including retry
records. Successful, retry, and source copies are deduplicated by their response,
provider-assigned message, or message identity.

## Configuration

Use the `antigravity` namespace for source-specific defaults and command
overrides in `ccusage.json`:

```json
{
	"antigravity": {
		"defaults": {
			"offline": true
		},
		"commands": {
			"daily": {
				"timezone": "UTC"
			}
		}
	}
}
```

## Troubleshooting

::: details No Antigravity usage data found
Check that the conversation databases exist below one of the default roots, or
set `ANTIGRAVITY_DATA_DIR` to the directory containing `conversations/`. The
databases must contain the `gen_metadata` table.
:::

::: details A database error is reported
ccusage does not turn unreadable or incomplete SQLite databases into an empty
report. Check the path in the error and ensure the database is readable and has
the expected `gen_metadata (idx, data)` schema.
:::

::: details Costs show as zero
Use `ccusage antigravity daily --mode calculate` and check the model name in
`--json` output. A model that is not in the embedded pricing catalog is reported
without an estimate; you can provide a pricing override through the normal
`pricingOverrides` configuration.
:::

---

---
url: /guide/kimi.md
---
# Kimi Data Source (Experimental)

> Kimi support is experimental. Expect breaking changes while both ccusage and [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) continue to evolve.

ccusage can read Kimi CLI wire logs as one of its supported local data sources. Kimi uses the same unified and focused report model as Claude Code, Codex, OpenCode, Amp, pi-agent, GitHub Copilot CLI, and Gemini CLI.

## Usage

```sh
# Daily Kimi usage
ccusage kimi daily

# Monthly Kimi usage
ccusage kimi monthly

# Kimi sessions
ccusage kimi session

# Include Kimi in the default all-source report
ccusage daily
```

## Data Location

The CLI reads Kimi wire JSONL files from `KIMI_DATA_DIR` (defaults to `~/.kimi` and `~/.kimi-code`). `KIMI_DATA_DIR` can be one directory or a comma-separated list of directories.

```sh
KIMI_DATA_DIR="$HOME/.kimi,/backup/kimi" ccusage kimi daily
```

Expected files are discovered under:

```text
~/.kimi/sessions/<group-id>/<session-id>/wire.jsonl
~/.kimi-code/sessions/<workspace-id>/<session-id>/agents/<agent-id>/wire.jsonl
```

## Supported Reports

| Command                | Description                 | Related Report                          |
| ---------------------- | --------------------------- | --------------------------------------- |
| `ccusage kimi daily`   | Group usage by day          | [Daily Usage](/guide/daily-reports)     |
| `ccusage kimi monthly` | Group usage by month        | [Monthly Usage](/guide/monthly-reports) |
| `ccusage kimi session` | Group usage by Kimi session | [Session Usage](/guide/session-reports) |

## Token Mapping

* **Input tokens** - `token_usage.input_other` (or `usage.inputOther` in Kimi Code logs)
* **Output tokens** - `token_usage.output` (or `usage.output`)
* **Cache read tokens** - `token_usage.input_cache_read` (or `usage.inputCacheRead`)
* **Cache creation tokens** - `token_usage.input_cache_creation` (or `usage.inputCacheCreation`)

Only `StatusUpdate` messages with non-zero token usage are included. Kimi Code logs instead emit `usage.record` lines; only turn-scoped records are counted, since session-scoped records are cumulative totals.

## Cost Calculation

Kimi rows do not store recorded USD cost, so ccusage estimates cost from token counts and LiteLLM pricing. The default `kimi-for-coding` model is kept as the displayed model name, but pricing resolves to Moonshot K2.5 before `2026-04-20T15:28:10.072Z` and Moonshot K2.6 at or after that timestamp.

## Environment Variables

| Variable        | Description                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `KIMI_DATA_DIR` | Override the root directory, or comma-separated root directories, containing Kimi data |

## Troubleshooting

::: details No Kimi usage data found
Ensure the data directory exists at `~/.kimi/sessions/` or `~/.kimi-code/sessions/`. Set `KIMI_DATA_DIR` if your Kimi data lives elsewhere or in multiple archive roots.
:::

---

---
url: /guide/openclaw.md
---
# OpenClaw Data Source (Experimental)

ccusage can experimentally read OpenClaw session data as one of its supported local data sources. OpenClaw is a multi-provider coding agent that stores per-message token usage and embedded cost data in JSONL session files.

## What is OpenClaw?

OpenClaw is a third-party coding (agent) CLI (previously known as `clawdbot`, `moltbot`, and `moldbot`) that records assistant messages with token counts, cache metrics, and per-message cost. ccusage reads these JSONL files and aggregates them alongside its other supported sources.

## Focused Views

```bash
# Recommended
bunx ccusage openclaw --help

# Alternative package runners
npx ccusage@latest openclaw --help
pnpm dlx ccusage openclaw --help
pnpx ccusage openclaw --help
```

## Data Source

The CLI scans these directories for OpenClaw session files:

| Source   | Default paths                                                | Override                             |
| -------- | ------------------------------------------------------------ | ------------------------------------ |
| OpenClaw | `~/.openclaw/`, `~/.clawdbot/`, `~/.moltbot/`, `~/.moldbot/` | `OPENCLAW_DIR` or `--open-claw-path` |

ccusage walks each root recursively (typically `<root>/agents/<agentId>/sessions/<uuid>.jsonl`) and also picks up archived transcripts named `<uuid>.jsonl.deleted.<timestamp>` and `<uuid>.jsonl.reset.<timestamp>` so previously consumed tokens remain visible in totals.

Since OpenClaw 2026.9.x stores live sessions in per-agent SQLite databases (`<root>/agents/<agentId>/agent/openclaw-agent.sqlite`), ccusage also reads assistant usage from each database's `transcript_events` table. The SQLite rows reuse the same token mapping and embedded `usage.cost` contract as the JSONL path, and win over migrated JSONL duplicates of the same event.

Both `OPENCLAW_DIR` and `--open-claw-path` can be one root directory or a comma-separated list of root directories.

## Report Views

```bash
# Show daily OpenClaw usage
ccusage openclaw daily

# Show monthly OpenClaw usage
ccusage openclaw monthly

# Show session-based OpenClaw usage
ccusage openclaw session

# JSON output for automation
ccusage openclaw daily --json

# Custom OpenClaw root
ccusage openclaw daily --open-claw-path /path/to/.openclaw

# Multiple OpenClaw roots
ccusage openclaw daily --open-claw-path /path/to/.openclaw,/archive/.clawdbot

# Filter by date range
ccusage openclaw daily --since 2026-05-01 --until 2026-05-16
```

## Cost Calculation

OpenClaw session messages embed a `cost.total` value per assistant message. In the default mode, ccusage uses these embedded costs directly, so reports work offline without `--offline`. With `--mode calculate`, ccusage resolves the raw model identity through the merged LiteLLM and models.dev pricing data; this includes timestamp-aware DeepSeek V4 rates when applicable.

## Model Attribution

OpenClaw sessions emit `model_change` and `custom`/`model-snapshot` events that set the active provider and model for subsequent assistant messages. ccusage tracks this state per file and tags every model name with an `[openclaw]` prefix in the `modelsUsed` column to keep it distinguishable in the unified `ccusage daily` view.

## Environment Variables

| Variable       | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `OPENCLAW_DIR` | Custom path, or comma-separated paths, to OpenClaw root directories |
| `LOG_LEVEL`    | Adjust logging verbosity (0 silent … 5 trace)                       |

## Daily View

This view shows daily usage from OpenClaw.

```bash
# Recommended (fastest)
bunx ccusage openclaw daily

# Using npx
npx ccusage@latest openclaw daily
```

### Options

| Flag               | Short | Description                                                         |
| ------------------ | ----- | ------------------------------------------------------------------- |
| `--since`          |       | Start date filter (YYYY-MM-DD or YYYYMMDD)                          |
| `--until`          |       | End date filter (YYYY-MM-DD or YYYYMMDD)                            |
| `--timezone`       | `-z`  | Override timezone for date grouping                                 |
| `--json`           | `-j`  | Emit structured JSON instead of a table                             |
| `--compact`        |       | Force compact table layout for narrow terminals                     |
| `--open-claw-path` |       | Custom path, or comma-separated paths, to OpenClaw root directories |

### Example Output

```text
┌────────────┬──────────────────────┬───────────┬───────────┬──────────────┬────────────┬──────────────┬──────────────┐
│ Date       │ Models               │     Input │    Output │ Cache Create │ Cache Read │ Total Tokens │   Cost (USD) │
├────────────┼──────────────────────┼───────────┼───────────┼──────────────┼────────────┼──────────────┼──────────────┤
│ 2026-05-16 │ - [openclaw] gpt-5.2 │     1,860 │        95 │          500 │    109,928 │      112,383 │        $0.03 │
├────────────┼──────────────────────┼───────────┼───────────┼──────────────┼────────────┼──────────────┼──────────────┤
│ Total      │                      │     1,860 │        95 │          500 │    109,928 │      112,383 │        $0.03 │
└────────────┴──────────────────────┴───────────┴───────────┴──────────────┴────────────┴──────────────┴──────────────┘
```

### JSON Output

Use `--json` for automation and scripting:

```bash
ccusage openclaw daily --json
```

Returns structured data:

```json
{
	"daily": [
		{
			"date": "2026-05-16",
			"inputTokens": 1860,
			"outputTokens": 95,
			"cacheCreationTokens": 500,
			"cacheReadTokens": 109928,
			"totalTokens": 112383,
			"totalCost": 0.03,
			"modelsUsed": ["[openclaw] gpt-5.2"]
		}
	],
	"totals": {
		"inputTokens": 1860,
		"outputTokens": 95,
		"cacheCreationTokens": 500,
		"cacheReadTokens": 109928,
		"totalTokens": 112383,
		"totalCost": 0.03
	}
}
```

## Monthly View

This view shows monthly usage from OpenClaw.

```bash
ccusage openclaw monthly
ccusage openclaw monthly --json
ccusage openclaw monthly --since 2026-01-01 --until 2026-03-31
```

## Session View

This view shows usage grouped by individual OpenClaw sessions. Session IDs come from the JSONL filename stem (the part before `.jsonl`, ignoring `.deleted.<ts>` or `.reset.<ts>` suffixes), and JSON output records activity timestamps and provider metadata for the most recent activity.

```bash
ccusage openclaw session
ccusage openclaw session --json
ccusage openclaw session --since 2026-05-09
```

### Example Output

```text
┌────────────┬──────────────────────┬───────────┬───────────┬──────────────┬────────────┬──────────────┬──────────────┐
│ Session    │ Models               │     Input │    Output │ Cache Create │ Cache Read │ Total Tokens │   Cost (USD) │
├────────────┼──────────────────────┼───────────┼───────────┼──────────────┼────────────┼──────────────┼──────────────┤
│ abc        │ - [openclaw] gpt-5.2 │     1,860 │        95 │          500 │    109,928 │      112,383 │        $0.03 │
├────────────┼──────────────────────┼───────────┼───────────┼──────────────┼────────────┼──────────────┼──────────────┤
│ Total      │                      │     1,860 │        95 │          500 │    109,928 │      112,383 │        $0.03 │
└────────────┴──────────────────────┴───────────┴───────────┴──────────────┴────────────┴──────────────┴──────────────┘
```

## Related

* [ccusage](https://github.com/ccusage/ccusage) - Main usage analysis tool for coding (agent) CLIs

---

---
url: /guide/grok.md
---
# Grok Build CLI Data Source

ccusage can read local Grok Build CLI session logs as a supported data source. Grok uses the same unified and focused report model as other agents.

## Focused Views

```bash
# Daily Grok usage
ccusage grok daily

# Monthly Grok usage
ccusage grok monthly

# Grok sessions
ccusage grok session
```

Most users can start with unified reports such as `ccusage daily`. Add the `grok` namespace only when you want to focus the same report shape on Grok usage.

## Data Source

The CLI reads completed turns from `updates.jsonl` under the Grok home directory.

Root resolution (highest first):

1. A non-empty `GROK_HOME` (official Grok environment variable)
2. `~/.grok`

```bash
GROK_HOME="$HOME/.grok" ccusage grok daily
```

```text
$GROK_HOME/   # or ~/.grok
└── sessions/
    └── <url-encoded-cwd>/
        └── <session-uuid>/
            ├── updates.jsonl  # PRIMARY (turn_completed + usage)
            └── summary.json   # optional metadata
```

Only rows with `sessionUpdate == "turn_completed"` and a usable usage breakdown are counted. In-progress turns are not included until they complete, and a session killed mid-turn never records one, so its usage cannot be reported. `logs/unified.jsonl` is not used as a source: it has no per-request model id, so its tokens cannot be priced or attributed to a model.

## Report Views

| Focused view           | Description                 | See also                                |
| ---------------------- | --------------------------- | --------------------------------------- |
| `ccusage grok daily`   | Aggregate usage by date     | [Daily Usage](/guide/daily-reports)     |
| `ccusage grok monthly` | Aggregate usage by month    | [Monthly Usage](/guide/monthly-reports) |
| `ccusage grok session` | Group usage by Grok session | [Session Usage](/guide/session-reports) |

These views support `--json`, `--compact`, `--mode`, and `--offline`.

Focused terminal tables omit the `Cache Create` column when the selected Grok
rows report no cache-creation tokens. The column reappears when selected rows
contain a non-zero value; [JSON output](/guide/json-output) keeps
`cacheCreationTokens` in the stable report schema either way.

## What Gets Calculated

* **Token usage** - Grok records OpenAI-style usage where `inputTokens` includes cache. ccusage splits it into uncached input, cache read (`cachedReadTokens`) and cache write (`cacheCreationTokens`), and stores the full `outputTokens` as output.
* **Reasoning tokens** - `reasoningTokens` are a subset of `outputTokens`, so they are already counted in the total. They are **not** added on top of output for either tokens or cost.
* **Precomputed cost** - Grok records `costUsdTicks` on each completed turn, in units of 1e-10 USD. ccusage uses it as the invoice cost, so `display` and the default `auto` report exactly what Grok billed.
* **Pricing** - `calculate`, and `auto` for turns that recorded no ticks, fall back to table estimates. Model ids such as `grok-4.5-build` try candidates with the trailing `-build` stripped and `xai/` / `x-ai/` prefixes, exact matches first. xAI's long-context rates apply when a turn's whole context — fresh input plus cache reads and writes — exceeds the model's boundary (200K for `grok-4.5` and `grok-4.6`). A `turn_completed` row aggregates several API requests, so the tier is chosen per turn rather than per request and the estimate only approximates the invoice.
* **Model labels** - Display form is the raw `modelUsage` key (e.g. `grok-4.5-build`). The Agent column identifies the Grok source in unified reports.

## Environment Variables

| Variable    | Description                                  |
| ----------- | -------------------------------------------- |
| `GROK_HOME` | Official Grok config/data home (single root) |
| `LOG_LEVEL` | Adjust verbosity (0 silent ... 5 trace)      |

## Configuration

```json
{
	"grok": {
		"defaults": {
			"offline": true
		},
		"commands": {
			"session": {
				"json": true
			}
		}
	}
}
```

The `grok` namespace supports the same shared report options as other focused
sources. Use `grok.defaults` for all Grok reports and a matching
`grok.commands.daily`, `grok.commands.monthly`, or `grok.commands.session`
object for report-specific overrides. The data root is discovered from
`GROK_HOME` or `~/.grok`, not from ccusage configuration.

## Troubleshooting

::: details No Grok usage data found
Ensure completed turns exist under `~/.grok/sessions/**/updates.jsonl`. In-progress turns do not appear until `turn_completed` is written. Set `GROK_HOME` if your data lives elsewhere.
:::

::: details Costs showing as $0.00
Turns written before Grok started recording `costUsdTicks` carry no cost, so `display` shows zero for them. Use `--mode calculate` to price those from the pricing tables instead. If a model is missing from pricing, the cost stays at zero and a missing-pricing warning may appear.
:::

::: details Totals lower than expected while a turn is open
v1 only counts completed turns. Finish the turn (or wait for `turn_completed`) and re-run the report.
:::

---

---
url: /guide/zcode.md
---
# ZCode Data Source

ccusage reads completed ZCode model-usage records from the local SQLite
database and exposes the same focused and unified reports as the other
supported sources.

## Focused Views

```bash
ccusage zcode daily
ccusage zcode monthly
ccusage zcode session
```

Use `ccusage daily`, `ccusage monthly`, or `ccusage session` when ZCode should
be included with every other detected source.

## Data Source

ZCode stores its usage ledger at `cli/db/db.sqlite` beneath its data root:

```text
$ZCODE_HOME/   # or ~/.zcode
└── cli/
    └── db/
        └── db.sqlite
```

Set `ZCODE_HOME` to one root or a comma-separated list of roots when usage data
is stored elsewhere. Roots and database paths are canonicalized and
deduplicated. When `ZCODE_HOME` is non-empty, invalid configured roots are
skipped and discovery does not fall back to `~/.zcode`.

The adapter validates the `model_usage` and `session` tables before reading
them. The required columns are `id`, `session_id`, `started_at`, `model_id`,
`status`, `input_tokens`, and `output_tokens` on `model_usage`, plus `id` and
`directory` on `session`. Optional cache, provider, computed-total, and session
version columns are detected individually. The presence of `session.version`
is reported as the session-versioned layout; older databases without it use
the legacy layout. Compatible additive schema changes are accepted, while
incomplete or unrelated databases are ignored.

Only rows whose status is exactly `completed` are counted. `started_at` is an
epoch-millisecond timestamp, so report dates retain sub-second precision in
the source entry. The read query selects only identifiers, timestamps, status,
token counters, model/provider metadata, and the session directory. Prompt,
content, and raw usage fields are not materialized.

Connections are opened read-only, use a busy timeout while ZCode may be
writing, and enable connection-local SQLite query-only mode. The adapter does
not change journal mode, so an existing ZCode WAL remains available for
concurrent reads.

## Token and Cost Handling

ZCode's `input_tokens` includes both cache-read and cache-creation tokens. The
adapter subtracts both buckets from fresh input and reports them separately.
Cache buckets are bounded by the inclusive input count, and any positive
remainder in `computed_total_tokens` is preserved by the shared extra-token
fallback.

ZCode does not record a per-request cost. `--mode display` therefore reports
zero cost. `--mode calculate` and `auto` use the shared model pricing map when
the model can be resolved. Built-in Z.ai pricing is selected for an explicit
Z.ai provider, or for legacy rows with no provider and a GLM model. A custom
provider UUID is not treated as a billable provider even when its model name
matches a generic pricing entry; use an explicit model pricing override when
that provider should be estimated. Unpriced models remain at zero cost and use
the standard missing-pricing warning. Z.ai cache-creation tokens remain in the
displayed cache-creation bucket but are estimated at the model's standard input
rate because they represent new content.

## Configuration

The `zcode` namespace supports the shared report options:

```json
{
	"zcode": {
		"defaults": {
			"offline": true
		},
		"commands": {
			"daily": {
				"json": true
			}
		}
	}
}
```

The data root is controlled by `ZCODE_HOME`; it is not a billing or provider
configuration setting.

## Report Views

| Focused view            | Description                  | See also                                |
| ----------------------- | ---------------------------- | --------------------------------------- |
| `ccusage zcode daily`   | Aggregate usage by date      | [Daily Usage](/guide/daily-reports)     |
| `ccusage zcode monthly` | Aggregate usage by month     | [Monthly Usage](/guide/monthly-reports) |
| `ccusage zcode session` | Group usage by ZCode session | [Session Usage](/guide/session-reports) |

These views support the standard `--json`, `--compact`, `--mode`, `--offline`,
`--since`, `--until`, and `--timezone` options.

## Troubleshooting

::: details No ZCode usage data found
Ensure `$ZCODE_HOME/cli/db/db.sqlite` or `~/.zcode/cli/db/db.sqlite` exists and contains the `model_usage` and `session` tables. Use `--debug` to see rejected roots, schema diagnostics, and database read errors.
:::

::: details Costs showing as $0.00
ZCode has no per-request cost field. Use `--mode calculate` to estimate rows whose model is in the pricing map. Custom provider UUIDs do not identify a billable provider, so unpriced custom models remain at zero.
:::

::: details Totals lower than expected while ZCode is open
Only completed model-usage rows are included. Wait for the turn to complete and rerun the report.
:::

---

---
url: /guide/source-support-qa.md
---
# Source Support Q\&A

ccusage only supports a coding agent when it can read local usage records with enough information to produce accurate reports. At minimum, a source needs local timestamps, session identity, model identity, and token counts or recorded costs that can be mapped to token usage.

If a tool stores only prompts, transcripts, quota percentages, or opaque cloud state, ccusage does not estimate token usage from text length. That would make daily, monthly, session, and cost reports look precise while being based on guesses.

## What Makes a Source Supportable?

A source is a good fit when its local files include most of the following:

* Per-message or per-turn token counts
* Input and output token counts, with cache and reasoning tokens when available
* Model identifiers for pricing
* Timestamps for date filtering and grouping
* Session or conversation identifiers
* Stable local file formats such as JSONL, SQLite tables, or structured telemetry exports

Local transcript text alone is not enough. A transcript can be useful for debugging, but it does not reveal tokenizer behavior, hidden system context, cached input, tool-call overhead, or provider-side accounting.

## Unsupported Sources Investigated

::: details Why is Devin CLI not supported?
Devin CLI usage information appears to live in Devin's cloud service rather than in a local usage log that ccusage can read. The locally available data did not provide direct access to historical token usage or costs.

ccusage is a local, read-only analyzer. It does not scrape private cloud services or depend on undocumented authenticated APIs for user usage history. If Devin adds a local export with timestamps, sessions, models, and token counts, support can be revisited.
:::

## Previously Unsupported, Now Supported

::: details Antigravity
Antigravity is now supported as its own source. ccusage reads the local
`gen_metadata` SQLite databases, keeps Antigravity separate from Gemini CLI,
and maps the input, cache-read, visible-output, and thinking-token buckets into
the standard report shape. See [Antigravity](/guide/antigravity/).
:::

::: details Grok Build CLI
Earlier investigations looked at local Grok data that did not expose usable token
accounting (for example SQLite without per-turn usage). Grok Build CLI is now
supported: ccusage reads completed turns from
`${GROK_HOME:-~/.grok}/sessions/**/updates.jsonl` (`sessionUpdate == "turn_completed"`
with `usage` / `modelUsage`). Costs come from Grok's own `costUsdTicks`, with
LiteLLM estimates as the fallback. In-progress turns count only after
`turn_completed`. See [Grok Build CLI](/guide/grok/).
:::

## Can These Be Added Later?

Yes. Open an issue if a tool starts writing local usage data with token counts or exposes an official export. Useful examples include:

* A sample redacted log file
* The default data directory
* A description of which fields represent input, output, cache, reasoning, model, timestamp, and session ID
* Notes about whether costs are recorded or should be calculated from model pricing

Please do not share secrets, API keys, OAuth tokens, raw private prompts, or full conversation transcripts.

---

---
url: /guide/configuration.md
---
# Configuration Overview

ccusage provides multiple ways to configure its behavior, allowing you to customize it for your specific needs. Configuration can be done through command-line options, environment variables, configuration files, or a combination of all three.

## Configuration Methods

ccusage supports four configuration methods, each with its own use case:

1. **[Command-Line Options](/guide/cli-options)** - Direct control for individual commands
2. **[Environment Variables](/guide/environment-variables)** - System-wide or session settings
3. **[Configuration Files](/guide/config-files)** - Persistent, shareable settings
4. **Data source directories** - Source-specific defaults and environment variable overrides

## Configuration Priority

Settings are applied in this priority order (highest to lowest):

1. **Command-line arguments** (e.g., `--json`, `--offline`)
2. **Custom config file** (via `--config` flag)
3. **Environment variables** (e.g., `CODEX_HOME`, `LOG_LEVEL`)
4. **Local project config** (`.ccusage/ccusage.json`)
5. **User config** (`~/.config/claude/ccusage.json`)
6. **Legacy user config** (`~/.claude/ccusage.json`)
7. **Built-in defaults**

### Priority Example

```bash
# Configuration file sets mode to "calculate"
# .ccusage/ccusage.json
{
  "defaults": {
    "mode": "calculate"
  }
}

# Environment variable sets timezone
export CCUSAGE_TIMEZONE="Asia/Tokyo"

# Command-line argument takes highest priority
ccusage daily --mode display --timezone UTC
# Result: mode=display (CLI), timezone=UTC (CLI)
```

## Quick Start

### Basic Setup

1. **Set custom data directories** (only if not using defaults):

```bash
export CODEX_HOME="$HOME/.codex"
export GEMINI_DATA_DIR="$HOME/.gemini/tmp"
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode"
export AMP_DATA_DIR="$HOME/.local/share/amp"
export PI_AGENT_DIR="$HOME/.pi/agent/sessions"
export KILO_DATA_DIR="$HOME/.local/share/kilo"
export COPILOT_HOME="$HOME/.copilot"
export COPILOT_OTEL_FILE_EXPORTER_PATH="$COPILOT_HOME/otel/copilot-otel.jsonl"
export ZCODE_HOME="$HOME/.zcode"
```

Use comma-separated directories when you want reports to combine multiple profiles or archives:

```bash
export CODEX_HOME="$HOME/.codex,$HOME/.codex-work"
export GEMINI_DATA_DIR="$HOME/.gemini/tmp,/backup/gemini/tmp"
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode,/archive/opencode"
export KILO_DATA_DIR="$HOME/.local/share/kilo,/backup/kilo"
```

2. **Create a configuration file** for your preferences:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "America/New_York",
		"breakdown": true
	}
}
```

3. **Use command-line options** for one-off changes:

```bash
ccusage daily --since 20260101 --json
```

## Common Configuration Scenarios

### Personal Development

For individual developers working on multiple projects:

```json
// ~/.config/claude/ccusage.json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"breakdown": true,
		"timezone": "local"
	},
	"commands": {
		"daily": {
			"instances": true
		}
	}
}
```

### Multiple Sources

Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode separately with data source namespaces:

```json
// ~/.config/claude/ccusage.json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "UTC"
	},
	"claude": {
		"commands": {
			"daily": {
				"instances": true
			}
		}
	},
	"codex": {
		"defaults": {
			"json": true,
			"offline": true
		},
		"commands": {
			"daily": {
				"since": "20260101",
				"until": "20260131"
			}
		}
	}
}
```

Source sections apply to focused commands such as `ccusage codex daily` and `ccusage amp session`. They are also used by unified reports such as `ccusage daily`, where each source receives its own merged options before data is loaded.

### Team Collaboration

For teams sharing configuration:

```json
// .ccusage/ccusage.json (committed to repo)
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "UTC",
		"mode": "auto"
	}
}
```

### CI/CD Pipeline

For automated environments:

```bash
# Environment variables
export CODEX_HOME="/ci/codex-data"
export LOG_LEVEL=1  # Warnings only

# Run with specific options
ccusage daily --offline --json > report.json
```

## Configuration by Feature

### Cost Calculation

Control how costs are calculated:

* **Mode**: `auto` (default), `calculate`, or `display`
* **Offline**: Use cached pricing data
* **Breakdown**: Show per-model costs

```bash
ccusage daily --mode calculate --breakdown --offline
```

### Date and Time

Customize date/time handling:

* **Timezone**: Any valid timezone (e.g., `UTC`, `America/New_York`)
* **Date Range**: Filter with `--since` and `--until`

```bash
ccusage daily --timezone UTC --since 20260101
```

### Output Format

Control output presentation:

* **JSON**: Machine-readable output with `--json`
* **Debug**: Show detailed information with `--debug`

```bash
ccusage daily --json | jq ".data[] | select(.cost > 10)"
```

### Project Analysis

Analyze usage by project:

* **Instances**: Group by project with `--instances`
* **Project Filter**: Focus on specific project with `--project`
* **Aliases**: Set custom names via configuration file

```json
// .ccusage/ccusage.json
{
	"commands": {
		"daily": {
			"projectAliases": "uuid-123=My App,long-name=Backend"
		}
	}
}
```

```bash
ccusage daily --instances --project "My App"
```

## Debugging Configuration

Use debug mode to understand configuration loading:

```bash
# See which config files are loaded
ccusage daily --debug

# Check environment variables
env | grep -E "CLAUDE|CCUSAGE|LOG_LEVEL"

# Verbose logging
LOG_LEVEL=5 ccusage daily
```

### Debug Output

Debug mode shows:

* Config file discovery and loading
* Option merging from different sources
* Final configuration values
* Pricing calculation details

## Best Practices

### 1. Layer Your Configuration

Use different configuration methods for different scopes:

* **Environment variables**: Machine-specific settings (paths)
* **User config**: Personal preferences (timezone)
* **Project config**: Team standards (mode, formatting)
* **CLI arguments**: One-off overrides

### 2. Use Configuration Files for Teams

Share consistent settings across team members:

```bash
# Commit to version control
git add .ccusage/ccusage.json
git commit -m "Add team ccusage configuration"
```

### 3. Document Your Configuration

Add comments or README files explaining configuration choices:

```markdown
# ccusage Configuration

Our team uses:

- UTC timezone for consistency
- JSON output for automated processing
- Calculate mode for accurate cost tracking
```

### 4. Validate Configuration

Use the schema for validation:

```json
{
	"$schema": "https://ccusage.com/config-schema.json"
}
```

### 5. Keep Secrets Secure

Never put sensitive information in configuration files:

* ❌ API keys or tokens
* ❌ Personal identifiers
* ✅ Timezone preferences
* ✅ Output formats

## Migration Guide

### From v1 to v2

If upgrading from older versions:

1. Update directory paths (now supports `~/.config/claude`)
2. Migrate environment variables to config files
3. Update any scripts using old CLI options

### From Manual Commands

Convert repeated commands to configuration:

```bash
# Before: Repeated commands
ccusage daily --breakdown --instances --timezone UTC

# After: Configuration file
{
  "defaults": {
    "breakdown": true,
    "timezone": "UTC"
  },
  "commands": {
    "daily": {
      "instances": true
    }
  }
}

# Simplified command
ccusage daily
```

## Troubleshooting

### Common Issues

1. **Configuration not applied**: Check priority order
2. **Invalid JSON**: Validate syntax with `jq`
3. **Directory not found**: Verify the data source environment variable
4. **No data**: Check directory permissions

### Getting Help

If configuration issues persist:

1. Run with debug mode: `ccusage daily --debug`
2. Check verbose logs: `LOG_LEVEL=5 ccusage daily`
3. Validate JSON config: `jq . < ccusage.json`
4. Report issues on [GitHub](https://github.com/ccusage/ccusage/issues)

## Next Steps

Explore specific configuration topics:

* [Command-Line Options](/guide/cli-options) - All available CLI arguments
* [Environment Variables](/guide/environment-variables) - System configuration
* [Configuration Files](/guide/config-files) - Persistent settings
* [Claude Code](/guide/claude/) - Claude Code data discovery
* [Cost Modes](/guide/cost-modes) - Understanding calculation modes
* [Claude Code](/guide/claude/) - Claude Code data paths and source-specific options

---

---
url: /guide/cli-options.md
---
# Command-Line Options

ccusage provides extensive command-line options to customize its behavior. These options take precedence over configuration files and environment variables.

## Global Options

All ccusage commands support these global options:

### Date Filtering

Filter usage data by date range:

```bash
# Filter by date range
ccusage daily --since 20260101 --until 20260531

# Show data from a specific date
ccusage monthly --since 20260101

# Show data up to a specific date
ccusage session --until 20260531
```

Both bounds accept `YYYY-MM-DD` or `YYYYMMDD` and are inclusive. Any other spelling, or a value that is not a real calendar date such as `2026-02-30`, is rejected with a non-zero exit code instead of silently changing which rows the report keeps. The same check applies to `since` and `until` in a [configuration file](/guide/config-files). A window whose `--since` date is later than its `--until` date is rejected the same way, whether the bounds come from flags, a configuration file, or a mix of both. `statusline` is exempt because it ignores report date filters, including configured defaults.

### Recent Periods

Instead of working out dates, ask for the most recent periods of whatever the report groups by:

```bash
# Today
ccusage daily --last 1

# This week
ccusage weekly --last 1

# This month
ccusage monthly --last 1

# The last seven days, and the last three months
ccusage daily --last 7
ccusage monthly --last 3
```

The count is inclusive of the current period, so `--last 2` on a daily report covers yesterday and today. Weeks start on the same day the report buckets by: Monday by default and Sunday for `ccusage claude weekly`, unless `commands.weekly.startOfWeek` in a [configuration file](/guide/config-files) or `--start-of-week` on `ccusage weekly` or `ccusage claude weekly` sets another day, with the flag taking precedence.

`--last` works on every daily, weekly, and monthly report, including the per-agent ones such as `ccusage codex daily --last 1`. It is not available on `session`, `blocks`, or `statusline`, which have no calendar period, and it cannot be combined with `--since`, `--until`, or `--sections`.

### Output Format

Control how data is displayed:

```bash
# JSON output for programmatic use
ccusage daily --json
ccusage daily -j

# Show per-model breakdown
ccusage daily --breakdown
ccusage daily -b

# Hide cost columns and JSON cost fields
ccusage daily --no-cost
ccusage daily --json --no-cost

# Combine options
ccusage daily --json --breakdown
```

`--no-cost` removes cost columns from table output and removes cost fields such as `totalCost`, `costUSD`, and `cost` from JSON output.

### Cost Calculation Mode

Choose how costs are calculated:

```bash
# Auto mode (default) - use costUSD when available
ccusage daily --mode auto

# Calculate mode - always calculate from tokens
ccusage daily --mode calculate

# Display mode - only show pre-calculated costUSD
ccusage daily --mode display
```

### Sort Order

Control the ordering of results:

```bash
# Newest first (default)
ccusage daily --order desc

# Oldest first
ccusage daily --order asc
```

### Offline Mode

Run without network connectivity:

```bash
# Use cached pricing data
ccusage daily --offline
ccusage daily -O
```

### Timezone

Set the timezone for date calculations:

```bash
# Use UTC timezone
ccusage daily --timezone UTC

# Use specific timezone
ccusage daily --timezone America/New_York
ccusage daily -z Asia/Tokyo

# Short alias
ccusage monthly -z Europe/London
```

The value must be `UTC`, another IANA timezone name, or `local` for the system timezone. An unknown name such as `Not/AZone` is rejected with a non-zero exit code instead of silently falling back to the system timezone, which can group usage under the wrong date. The same check applies to `timezone` in a [configuration file](/guide/config-files).

#### Timezone Effect

The timezone affects how usage is grouped by date. For example, usage at 11 PM UTC on January 1st would appear on:

* **January 1st** when `--timezone UTC`
* **January 1st** when `--timezone America/New_York` (6 PM EST)
* **January 2nd** when `--timezone Asia/Tokyo` (8 AM JST next day)

### Debug Options

Get detailed debugging information:

```bash
# Debug mode - show pricing mismatches and config loading
ccusage daily --debug

# Show sample discrepancies
ccusage daily --debug --debug-samples 10
```

### Configuration File

Use a custom configuration file:

```bash
# Specify custom config file
ccusage daily --config ./my-config.json
ccusage monthly --config /path/to/team-config.json
```

## Command-Specific Options

### Unified Report Options

These options apply to `ccusage daily`, `ccusage weekly`, `ccusage monthly`, and `ccusage session` when they are aggregating all detected sources:

```bash
# Emit several JSON report sections from one source load
ccusage daily --sections daily,monthly,session --json

# Add per-agent breakdowns to daily, weekly, and monthly JSON rows
ccusage daily --by-agent --json
```

`--sections` accepts a comma-separated list of `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included. For table output, each requested section is printed as a separate table. `--by-agent` is JSON-only; session rows are already per-agent.

### Daily Command

Additional options for daily reports:

```bash
# Group by project
ccusage daily --instances
ccusage daily -i

# Filter to specific project
ccusage daily --project myproject
ccusage daily -p myproject

# Combine project filtering
ccusage daily --instances --project myproject
```

### Weekly Command

Options for weekly reports:

```bash
# Set week start day
ccusage weekly --start-of-week monday
ccusage weekly --start-of-week sunday
```

### Session Command

Options for session reports:

```bash
# Filter by session ID
ccusage claude session --id abc123-session
ccusage codex session --id 01a0bb8c-c7c0-7630-9d82-860b875930f0

# Filter by project
ccusage session --project myproject
```

### Blocks Command

Options for 5-hour billing blocks:

```bash
# Show only active block
ccusage blocks --active
ccusage blocks -a

# Show recent blocks (last 3 days)
ccusage blocks --recent
ccusage blocks -r

# Set token limit for warnings
ccusage blocks --token-limit 500000
ccusage blocks --token-limit max

# Live monitoring mode
ccusage blocks --live
ccusage blocks --live --refresh-interval 2

# Customize session length
ccusage blocks --session-length 5
```

### Statusline

Options for statusline display:

```bash
# Basic statusline
ccusage statusline

# Force offline mode
ccusage statusline --offline

# Enable caching
ccusage statusline --cache

# Custom refresh interval
ccusage statusline --refresh-interval 5
```

## JSON Output

```bash
# Print JSON output
ccusage daily --json

# Print JSON without cost fields
ccusage daily --json --no-cost

# Pipe JSON output to jq
ccusage daily --json | jq ".data[]"

# Extract specific fields
ccusage session --json | jq ".data[] | {date, cost}"
```

## Option Precedence

Options are applied in this order (highest to lowest priority):

1. **Command-line arguments** - Direct CLI options
2. **Custom config file** - Via `--config` flag
3. **Local project config** - `.ccusage/ccusage.json`
4. **User config** - `~/.config/claude/ccusage.json`
5. **Legacy config** - `~/.claude/ccusage.json`
6. **Built-in defaults**

## Examples

### Development Workflow

```bash
# Daily development check
ccusage daily --instances --breakdown

# Check specific project costs
ccusage daily --project myapp --since 20260101

# Export for reporting
ccusage monthly --json > monthly-report.json
```

### Team Collaboration

```bash
# Use team configuration
ccusage daily --config ./team-config.json

# Consistent timezone for remote team
ccusage daily --timezone UTC

# Generate shareable report
ccusage weekly --json
```

### Cost Monitoring

```bash
# Monitor active usage
ccusage blocks --active --live

# Check if approaching limits
ccusage blocks --token-limit 500000

# Historical analysis
ccusage monthly --mode calculate --breakdown
```

### Debugging Issues

```bash
# Debug configuration loading
ccusage daily --debug --config ./test-config.json

# Check pricing discrepancies
ccusage daily --debug --debug-samples 20

# Silent mode for scripts
LOG_LEVEL=0 ccusage daily --json
```

## Short Aliases

Many options have short aliases for convenience:

| Long Option   | Short | Description         |
| ------------- | ----- | ------------------- |
| `--json`      | `-j`  | JSON output         |
| `--breakdown` | `-b`  | Per-model breakdown |
| `--offline`   | `-O`  | Offline mode        |
| `--timezone`  | `-z`  | Set timezone        |
| `--instances` | `-i`  | Group by project    |
| `--project`   | `-p`  | Filter project      |
| `--active`    | `-a`  | Active block only   |
| `--recent`    | `-r`  | Recent blocks       |

## Related Documentation

* [Environment Variables](/guide/environment-variables) - Configure via environment
* [Configuration Files](/guide/config-files) - Persistent configuration
* [Cost Calculation Modes](/guide/cost-modes) - Understanding cost modes

---

---
url: /guide/environment-variables.md
---
# Environment Variables

ccusage supports several environment variables for configuration and customization. Environment variables provide a way to configure ccusage without modifying command-line arguments or configuration files.

## Agent Data Directories

ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Directory variables can be one directory or a comma-separated list of directories; `COPILOT_HOME` and `GROK_HOME` accept a single root, while `COPILOT_OTEL_FILE_EXPORTER_PATH` points at one explicit JSONL export file:

| Variable                          | Agent          | Default                                              |
| --------------------------------- | -------------- | ---------------------------------------------------- |
| `CLAUDE_CONFIG_DIR`               | Claude Code    | `~/.config/claude` and `~/.claude`                   |
| `CODEX_HOME`                      | Codex          | `~/.codex`                                           |
| `OPENCODE_DATA_DIR`               | OpenCode       | `${XDG_DATA_HOME:-$HOME/.local/share}/opencode`      |
| `AMP_DATA_DIR`                    | Amp            | `~/.local/share/amp`                                 |
| `DROID_SESSIONS_DIR`              | Droid          | `~/.factory/sessions`                                |
| `CODEBUFF_DATA_DIR`               | Codebuff       | `~/.config/manicode`                                 |
| `HERMES_HOME`                     | Hermes Agent   | `~/.hermes`                                          |
| `PI_AGENT_DIR`                    | pi-agent       | `~/.pi/agent/sessions`                               |
| `GOOSE_PATH_ROOT`                 | Goose          | Standard Goose data roots                            |
| `OPENCLAW_DIR`                    | OpenClaw       | `~/.openclaw`                                        |
| `KILO_DATA_DIR`                   | Kilo           | `~/.local/share/kilo`                                |
| `KIMI_DATA_DIR`                   | Kimi           | `~/.kimi`, `~/.kimi-code`                            |
| `QWEN_DATA_DIR`                   | Qwen           | `~/.qwen`                                            |
| `COPILOT_HOME`                    | Copilot CLI    | `~/.copilot`                                         |
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Copilot CLI    | Explicit `.jsonl` file                               |
| `GEMINI_DATA_DIR`                 | Gemini CLI     | `~/.gemini/tmp`                                      |
| `ANTIGRAVITY_DATA_DIR`            | Antigravity    | `~/.gemini/antigravity*` and `~/.config/antigravity` |
| `GROK_HOME`                       | Grok Build CLI | `~/.grok`                                            |
| `ZCODE_HOME`                      | ZCode          | `~/.zcode`                                           |

Example:

```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 COPILOT_HOME="/path/to/copilot"
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
export GEMINI_DATA_DIR="/path/to/gemini/tmp,/archive/gemini/tmp"
export ANTIGRAVITY_DATA_DIR="/path/to/antigravity,/archive/antigravity"
export GROK_HOME="/path/to/grok-home"
export ZCODE_HOME="/path/to/zcode-home,/archive/zcode-home"
ccusage daily
```

Empty entries, directories that do not exist, and missing explicit files are skipped. Duplicate paths are read once. A non-empty `ZCODE_HOME` containing only invalid roots does not fall back to `~/.zcode`.

## CLAUDE_CONFIG_DIR

Specifies where ccusage should look for Claude Code data. See [Claude Code](/guide/claude/) for default paths, multiple-directory behavior, and Claude-specific examples.

## LOG_LEVEL

Controls the verbosity of log output.

### Log Levels

| Level  | Value | Description                  | Use Case               |
| ------ | ----- | ---------------------------- | ---------------------- |
| Silent | `0`   | Errors only                  | Scripts, piping output |
| Warn   | `1`   | Warnings and errors          | CI/CD environments     |
| Log    | `2`   | Normal logs                  | General use            |
| Info   | `3`   | Informational logs (default) | Standard operation     |
| Debug  | `4`   | Debug information            | Troubleshooting        |
| Trace  | `5`   | All operations               | Deep debugging         |

### Usage Examples

```bash
# Silent mode - only show results
LOG_LEVEL=0 ccusage daily

# Warning level - for CI/CD
LOG_LEVEL=1 ccusage monthly

# Debug mode - troubleshooting
LOG_LEVEL=4 ccusage session

# Trace everything - deep debugging
LOG_LEVEL=5 ccusage blocks
```

### Practical Applications

#### Clean Output for Scripts

```bash
# Get clean JSON output without logs
LOG_LEVEL=0 ccusage daily --json | jq '.summary.totalCost'
```

#### CI/CD Pipeline

```bash
# Show only warnings and errors in CI
LOG_LEVEL=1 ccusage daily --instances
```

#### Debugging Issues

```bash
# Maximum verbosity for troubleshooting
LOG_LEVEL=5 ccusage daily --debug
```

#### Piping Output

```bash
# Silent logs when piping to other commands
LOG_LEVEL=0 ccusage monthly --json | python analyze.py
```

## Additional Environment Variables

### CCUSAGE_OFFLINE

Force offline mode by default:

```bash
export CCUSAGE_OFFLINE=1
ccusage daily  # Runs in offline mode
```

### NO_COLOR

Disable colored output (standard CLI convention):

```bash
export NO_COLOR=1
ccusage daily  # No color formatting
```

### FORCE_COLOR

Force colored output even when piping:

```bash
export FORCE_COLOR=1
ccusage daily | less -R  # Preserves colors
```

## Setting Environment Variables

### Temporary (Current Session)

```bash
# Set for single command
LOG_LEVEL=0 ccusage daily

# Set for current shell session
export CODEX_HOME="/path/to/codex,/archive/codex"
ccusage daily
```

### Permanent (Shell Profile)

Add to your shell configuration file:

#### Bash (~/.bashrc)

```bash
export CODEX_HOME="$HOME/.codex"
export LOG_LEVEL=3
```

#### Zsh (~/.zshrc)

```zsh
export CODEX_HOME="$HOME/.codex"
export LOG_LEVEL=3
```

#### Fish (~/.config/fish/config.fish)

```fish
set -x CODEX_HOME "$HOME/.codex"
set -x LOG_LEVEL 3
```

#### PowerShell (Profile.ps1)

```powershell
$env:CODEX_HOME = "$env:USERPROFILE\.codex"
$env:LOG_LEVEL = "3"
```

## Precedence

Environment variables have lower precedence than command-line arguments but higher than configuration files:

1. **Command-line arguments** (highest priority)
2. **Environment variables**
3. **Configuration files**
4. **Built-in defaults** (lowest priority)

Example:

```bash
# Environment variable sets offline mode
export CCUSAGE_OFFLINE=1

# But command-line argument overrides it
ccusage daily --no-offline  # Runs in online mode
```

## Debugging

To see which environment variables are being used:

```bash
# Show all environment variables
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|DROID|CODEBUFF|HERMES|PI_AGENT|GOOSE|OPENCLAW|KILO|KIMI|QWEN|COPILOT|GEMINI|GROK|ZCODE|CCUSAGE|LOG_LEVEL"

# Debug mode shows environment variable usage
LOG_LEVEL=4 ccusage daily --debug
```

## Related Documentation

* [Command-Line Options](/guide/cli-options) - CLI arguments and flags
* [Configuration Files](/guide/config-files) - JSON configuration files
* [Configuration Overview](/guide/configuration) - Complete configuration guide

---

---
url: /guide/config-files.md
---
# Configuration Files

ccusage supports JSON configuration files for persistent settings. Configuration files allow you to set default options for all commands or customize behavior for specific commands without repeating options every time.

## Quick Start

### 1. Use Schema for IDE Support

Always include the schema for autocomplete and validation:

```json
{
	"$schema": "https://ccusage.com/config-schema.json"
}
```

### 2. Set Common Defaults

Put frequently used options in `defaults`:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"timezone": "UTC",
		"breakdown": true
	}
}
```

### 3. Override for Specific Commands

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"breakdown": false
	},
	"commands": {
		"daily": {
			"breakdown": true // Only daily needs breakdown
		}
	}
}
```

### 4. Convert CLI Arguments to Config

If you find yourself repeating CLI arguments:

```bash
# Before (repeated CLI arguments)
ccusage daily --breakdown --instances --timezone UTC
ccusage monthly --breakdown --timezone UTC
```

Convert them to a config file:

```json
// ccusage.json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"breakdown": true,
		"timezone": "UTC"
	},
	"commands": {
		"daily": {
			"instances": true
		}
	}
}
```

Now simpler commands:

```bash
ccusage daily
ccusage monthly
```

## Configuration File Locations

ccusage searches for configuration files in these locations (in priority order):

1. **Local project**: `.ccusage/ccusage.json` (higher priority)
2. **User config**: `~/.claude/ccusage.json` or `~/.config/claude/ccusage.json` (lower priority)

Configuration files are merged in priority order, with local project settings overriding user settings.
If you pass a custom config file using `--config`, it will override both local and user configs.
Note that configuration files are not required; if none are found, ccusage will use built-in defaults.
Also, if you have multiple config files, only the first one found will be used.

## Basic Configuration

Create a `ccusage.json` file with your preferred defaults:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"json": false,
		"mode": "auto",
		"offline": false,
		"noCost": false,
		"timezone": "Asia/Tokyo",
		"breakdown": true
	}
}
```

## Configuration Structure

### Schema Support

Add the `$schema` property to get IntelliSense and validation in your IDE:

```json
{
	"$schema": "https://ccusage.com/config-schema.json"
}
```

You can also reference a local schema file after installing ccusage:

```json
{
	"$schema": "./node_modules/ccusage/config-schema.json"
}
```

### Global Defaults

The `defaults` section sets shared default values for unified reports and legacy Claude commands:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"since": "20260101",
		"until": "20260531",
		"json": false,
		"mode": "auto",
		"debug": false,
		"debugSamples": 5,
		"order": "asc",
		"breakdown": false,
		"offline": false,
		"noCost": false,
		"timezone": "UTC"
	}
}
```

Set `noCost` to `true` to hide cost columns in tables and remove cost fields from JSON output by default.

### Command-Specific Configuration

Override shared defaults for specific unified reports and legacy Claude commands using the `commands` section:

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"mode": "auto",
		"offline": false
	},
	"commands": {
		"daily": {
			"instances": true,
			"breakdown": true
		},
		"blocks": {
			"active": true,
			"tokenLimit": "500000"
		}
	}
}
```

### Source-Specific Configuration

Use data source namespaces to set defaults and report overrides. Supported namespaces are `claude`, `codex`, `opencode`, `amp`, `droid`, `codebuff`, `hermes`, `pi`, `goose`, `openclaw`, `kilo`, `kimi`, `qwen`, `copilot`, `gemini`, `antigravity`, `grok`, and `zcode`.

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"json": false,
		"timezone": "UTC"
	},
	"codex": {
		"defaults": {
			"json": true,
			"offline": true
		},
		"commands": {
			"daily": {
				"since": "20260101",
				"until": "20260131"
			}
		}
	},
	"opencode": {
		"commands": {
			"weekly": {
				"timezone": "Europe/London"
			}
		}
	},
	"droid": {
		"defaults": {
			"offline": true
		}
	},
	"codebuff": {
		"commands": {
			"daily": {
				"json": true
			}
		}
	},
	"pi": {
		"stores": [
			{
				"name": "omp",
				"path": "~/.omp/agent/sessions"
			}
		],
		"defaults": {
			"piPath": "/path/to/pi/sessions,/archive/pi/sessions"
		}
	},
	"openclaw": {
		"defaults": {
			"openClawPath": "/path/to/openclaw,/archive/openclaw"
		}
	},
	"kilo": {
		"defaults": {
			"offline": true
		}
	},
	"kimi": {
		"defaults": {
			"offline": true
		}
	},
	"qwen": {
		"defaults": {
			"offline": true
		}
	},
	"copilot": {
		"defaults": {
			"offline": true
		}
	},
	"gemini": {
		"defaults": {
			"offline": true
		}
	},
	"zcode": {
		"defaults": {
			"offline": true
		}
	}
}
```

This configuration affects source-focused commands such as:

```bash
ccusage codex daily
ccusage opencode weekly
ccusage droid daily
ccusage codebuff daily
ccusage pi daily
ccusage openclaw daily
ccusage kilo daily
ccusage kimi daily
ccusage qwen daily
ccusage copilot monthly
ccusage gemini daily
ccusage antigravity daily
ccusage zcode daily
```

Source-specific settings are also applied when running unified reports such as `ccusage daily`. In that case, each source receives its own merged options before data is loaded.

Use `pi.stores` for additional pi-format session stores, such as tools or forks that write sessions outside `~/.pi/agent/sessions`. Named stores are additive to the default `pi` agent in unified reports, use their own agent name in JSON and tables, and prefix models with `[name]` followed by a space. Store names must match `^[a-z][a-z0-9_-]{0,31}$`, must be unique, and cannot use a built-in agent name. Each store path can be one sessions directory or a comma-separated list; `~` is expanded for store paths, nonexistent paths are treated as empty, and resolved paths that overlap the default `pi` store or another named store — including one path nested inside another — are rejected. They do not create focused commands such as `ccusage omp daily`; `PI_AGENT_DIR`, `--pi-path`, and `pi.defaults.piPath` still affect only the default `pi` agent.

For a namespaced command, options are applied in this order:

1. `defaults`
2. `commands.<report>`
3. `<source>.defaults`
4. `<source>.commands.<report>`
5. Command-line arguments

## Command-Specific Options

### Daily Command

```json
{
	"commands": {
		"daily": {
			"instances": true,
			"project": "my-project",
			"breakdown": true,
			"since": "20260101",
			"until": "20260531"
		}
	}
}
```

### Weekly Command

```json
{
	"commands": {
		"weekly": {
			"startOfWeek": "monday",
			"breakdown": true,
			"timezone": "Europe/London"
		}
	}
}
```

### Monthly Command

```json
{
	"commands": {
		"monthly": {
			"breakdown": true,
			"mode": "calculate"
		}
	}
}
```

### Session Command

```json
{
	"commands": {
		"session": {
			"id": "abc123-session",
			"project": "my-project",
			"json": true
		}
	}
}
```

### Blocks Command

```json
{
	"commands": {
		"blocks": {
			"active": true,
			"recent": false,
			"tokenLimit": "max",
			"sessionLength": 5,
			"live": false,
			"refreshInterval": 1
		}
	}
}
```

### Statusline

```json
{
	"commands": {
		"statusline": {
			"offline": true,
			"cache": true,
			"refreshInterval": 2,
			"modelLabelAliases": {
				"arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345": "claude-opus-4-6"
			}
		}
	}
}
```

## Custom Configuration Files

Use the `--config` option to specify a custom configuration file:

```bash
# Use a specific configuration file
ccusage daily --config ./my-config.json

# Works with all commands
ccusage blocks --config /path/to/team-config.json
```

## Pricing Overrides

ccusage looks up token costs from a LiteLLM pricing snapshot embedded in the binary, optionally refreshed at runtime (or skipped with `--offline`). When a model is missing from LiteLLM (private deployments, internal wrappers like Pi's `[pi] gpt-5.4`, custom proxies), or when the snapshot price differs from your contract, set `pricingOverrides` under `defaults` to supply per-model values.

```json
{
	"$schema": "https://ccusage.com/config-schema.json",
	"defaults": {
		"pricingOverrides": {
			"[pi] gpt-5.4": {
				"inputCostPerToken": 0.0000025,
				"outputCostPerToken": 0.000015,
				"cacheReadInputTokenCost": 0.00000025
			},
			"my-private-claude": {
				"inputCostPerToken": 0.000003,
				"outputCostPerToken": 0.000015,
				"maxInputTokens": 1000000
			}
		}
	}
}
```

### Raw Model Names

Keys in `pricingOverrides` should match the model label reported by ccusage, including any adapter prefix:

| Adapter                                | Prefix    | Example key                    |
| -------------------------------------- | --------- | ------------------------------ |
| Pi                                     | `[pi] `   | `[pi] gpt-5.4`                 |
| Named Pi store                         | `[name] ` | `[omp] gpt-5.4`                |
| Others (Claude, Codex, OpenCode, etc.) | none      | `claude-sonnet-4-5`, `gpt-5.5` |

To find the exact name, run `ccusage <agent> daily --json` and look at the `model` field in the per-row breakdown.
Pi also accepts a bare model name as an override key; that key applies to the default store and any named Pi store using the same model. Use the prefixed label to price one store separately.

### Supported Fields

All fields are optional. Unspecified fields keep existing values. Without a pricing entry, token rates default to `0.0` and speed multipliers to `1.0`.

* `inputCostPerToken`, `outputCostPerToken` — base per-token rates
* `cacheCreationInputTokenCost`, `cacheReadInputTokenCost` — cache pricing
* `inputCostPerTokenAbove200kTokens`, `outputCostPerTokenAbove200kTokens`, `cacheCreationInputTokenCostAbove200kTokens`, `cacheReadInputTokenCostAbove200kTokens` — tiered pricing past 200k tokens
* `maxInputTokens` — context window limit (used by the Claude statusline hook)
* `fastMultiplier` applies when Codex usage uses Fast pricing.
* `flexMultiplier` applies when Codex usage uses Flex pricing.

### Overrides vs Offline Mode

`--offline` and `pricingOverrides` are independent:

* `--offline` controls the **data source** — skip the network refresh and use the embedded LiteLLM snapshot only.
* `pricingOverrides` controls **specific entries** — patch in or replace prices for individual models.

Overrides apply in both online and offline modes.

For Pi and named Pi stores, Auto mode uses an explicit override to calculate cost from tokens even when the session contains a recorded cost. Display mode continues to show the recorded cost.

This is useful for:

* **Team configurations** - Share configuration files across team members
* **Environment-specific settings** - Different configs for development/production
* **Project-specific overrides** - Use different settings for different projects

## Configuration Example

For a complete configuration example, see [`/ccusage.example.json`](/ccusage.example.json) in the repository root, which demonstrates:

* Global defaults configuration
* Command-specific overrides
* All available options with proper types

## Configuration Priority

Settings are applied in this priority order (highest to lowest):

1. **Command-line arguments** (e.g., `--json`, `--offline`)
2. **Custom config file** (specified with `--config /path/to/config.json`)
3. **Local project config** (`.ccusage/ccusage.json`)
4. **User config** (`~/.config/claude/ccusage.json`)
5. **Legacy config** (`~/.claude/ccusage.json`)
6. **Built-in defaults**

Example:

```json
// .ccusage/ccusage.json
{
	"defaults": {
		"mode": "calculate"
	}
}
```

```bash
# Config file sets mode to "calculate"
ccusage daily  # Uses mode: calculate

# But CLI argument overrides it
ccusage daily --mode display  # Uses mode: display
```

## Debugging Configuration

Use the `--debug` flag to see configuration loading details:

```bash
# Debug configuration loading
ccusage daily --debug

# Debug custom config file
ccusage daily --debug --config ./my-config.json
```

Debug output shows:

* Which config files are checked and found
* Schema and option details from loaded configs
* How options are merged from different sources
* Final values used for each option

Example debug output:

```
[ccusage] ℹ Debug mode enabled - showing config loading details

[ccusage] ℹ Searching for config files:
  • Checking: .ccusage/ccusage.json (found ✓)
  • Checking: ~/.config/claude/ccusage.json (found ✓)
  • Checking: ~/.claude/ccusage.json (not found)

[ccusage] ℹ Loaded config from: .ccusage/ccusage.json
  • Schema: https://ccusage.com/config-schema.json
  • Has defaults: yes (3 options)
  • Has command configs: yes (daily)

[ccusage] ℹ Merging options for 'daily' command:
  • From defaults: mode="auto", offline=false
  • From command config: instances=true
  • From CLI args: debug=true
  • Final merged options: {
      mode: "auto" (from defaults),
      offline: false (from defaults),
      instances: true (from command config),
      debug: true (from CLI)
    }
```

## Best Practices

### Version Control

For project configs, commit `.ccusage/ccusage.json` to version control:

```bash
# Add to git
git add .ccusage/ccusage.json
git commit -m "Add ccusage configuration"
```

### Document Team Configs

Add comments using a README alongside team configs:

```
team-configs/
├── ccusage.json
└── README.md  # Explain configuration choices
```

## Troubleshooting

### Config Not Being Applied

1. Check file location is correct
2. Verify JSON syntax is valid
3. Use `--debug` to see loading details
4. Ensure option names match exactly

### Invalid JSON

Use a JSON validator or IDE with JSON support:

```bash
# Validate JSON syntax
jq . < ccusage.json
```

### Schema Validation Errors

Ensure option values match expected types:

```json
{
	"defaults": {
		"tokenLimit": "500000", // ✅ String or number
		"active": true, // ✅ Boolean
		"refreshInterval": 2 // ✅ Number
	}
}
```

## Related Documentation

* [Command-Line Options](/guide/cli-options) - Available CLI arguments
* [Environment Variables](/guide/environment-variables) - Environment configuration
* [Configuration Overview](/guide/configuration) - Complete configuration guide

---

---
url: /guide/cost-modes.md
---
# Cost Modes

ccusage supports three different cost calculation modes to handle various scenarios and data sources. Understanding these modes helps you get the most accurate cost estimates for your usage analysis.

## Overview

Claude Code stores usage data in JSONL files with both token counts and pre-calculated cost information. ccusage can handle this data in different ways depending on your needs:

* **`auto`** - Smart mode using the best available data
* **`calculate`** - Always calculate from token counts
* **`display`** - Only show pre-calculated costs

## Mode Details

### auto (Default)

The `auto` mode intelligently chooses the best cost calculation method for each entry:

```bash
ccusage daily --mode auto
# or simply:
ccusage daily
```

#### How it works:

1. **Pre-calculated costs available** → Uses Claude's `costUSD` values
2. **No pre-calculated costs** → Calculates from token counts using model pricing
3. **Mixed data** → Uses the best method for each entry; JSON output reports the stored part of each model's cost as [`storedCost`](/guide/json-output#stored-costs)

#### Best for:

* ✅ **General usage** - Works well for most scenarios
* ✅ **Mixed data sets** - Handles old and new data properly
* ✅ **Accuracy** - Uses official costs when available
* ✅ **Completeness** - Shows estimates for all entries

#### Example output:

```
┌──────────────┬─────────────┬────────┬─────────┬────────────┐
│ Date         │ Models      │ Input  │ Output  │ Cost (USD) │
├──────────────┼─────────────┼────────┼─────────┼────────────┤
│ 2026-05-16   │ • opus-4-1    │  1,245 │  28,756 │    $12.45  │ ← Pre-calculated
│ 2026-05-15   │ • sonnet-4-5  │    856 │  19,234 │     $8.67  │ ← Calculated
│ 2026-05-14   │ • opus-4-1    │    634 │  15,678 │     $7.23  │ ← Calculated
└──────────────┴─────────────┴────────┴─────────┴────────────┘
```

### calculate

The `calculate` mode always computes costs from token counts using model pricing:

```bash
ccusage daily --mode calculate
ccusage monthly --mode calculate --breakdown
```

#### How it works:

1. **Ignores `costUSD` values** from Claude Code data
2. **Uses token counts** (input, output, cache) for all entries
3. **Applies model pricing** from LiteLLM, models.dev, and built-in historical schedules using each event's timestamp
4. **Consistent methodology** across all time periods

#### Best for:

* ✅ **Consistent comparisons** - Same calculation method for all data
* ✅ **Token analysis** - Understanding pure token-based costs
* ✅ **Historical analysis** - Comparing costs across different time periods
* ✅ **Pricing research** - Analyzing cost per token trends

#### Example output:

```
┌──────────────┬─────────────┬────────┬─────────┬────────────┐
│ Date         │ Models      │ Input  │ Output  │ Cost (USD) │
├──────────────┼─────────────┼────────┼─────────┼────────────┤
│ 2026-05-16   │ • opus-4-1    │  1,245 │  28,756 │    $12.38  │ ← Calculated
│ 2026-05-15   │ • sonnet-4-5  │    856 │  19,234 │     $8.67  │ ← Calculated
│ 2026-05-14   │ • opus-4-1    │    634 │  15,678 │     $7.23  │ ← Calculated
└──────────────┴─────────────┴────────┴─────────┴────────────┘
```

### display

The `display` mode only shows pre-calculated costs from Claude Code:

```bash
ccusage daily --mode display
ccusage session --mode display --json
```

#### How it works:

1. **Uses only `costUSD` values** from Claude Code data
2. **Shows $0.00** for entries without pre-calculated costs
3. **No token-based calculations** performed
4. **Exact Claude billing data** when available

#### Best for:

* ✅ **Official costs only** - Shows exactly what Claude calculated
* ✅ **Billing verification** - Comparing with actual Claude charges
* ✅ **Recent data** - Most accurate for newer usage entries
* ✅ **Audit purposes** - Verifying pre-calculated costs

#### Example output:

```
┌──────────────┬─────────────┬────────┬─────────┬────────────┐
│ Date         │ Models      │ Input  │ Output  │ Cost (USD) │
├──────────────┼─────────────┼────────┼─────────┼────────────┤
│ 2026-05-16   │ • opus-4-1    │  1,245 │  28,756 │    $12.45  │ ← Pre-calculated
│ 2026-05-15   │ • sonnet-4-5  │    856 │  19,234 │     $0.00  │ ← No cost data
│ 2026-05-14   │ • opus-4-1    │    634 │  15,678 │     $0.00  │ ← No cost data
└──────────────┴─────────────┴────────┴─────────┴────────────┘
```

## Practical Examples

### Scenario 1: Mixed Data Analysis

You have data from different time periods with varying cost information:

```bash
# Auto mode handles mixed data intelligently
ccusage daily --mode auto --since 20260501

# Shows:
# - Pre-calculated costs where the source provides them
# - Calculated costs where only token counts are available
```

### Scenario 2: Consistent Cost Comparison

You want to compare costs across different months using the same methodology:

```bash
# Calculate mode ensures consistent methodology
ccusage monthly --mode calculate --breakdown

# All months use the same token-based calculation
# Useful for trend analysis and cost projections
```

### Scenario 3: Billing Verification

You want to verify Claude's official cost calculations:

```bash
# Display mode shows only official Claude costs
ccusage daily --mode display --since 20260101

# Compare with your Claude billing dashboard
# Entries without costs show $0.00
```

### Scenario 4: Historical Analysis

Analyzing usage patterns over time:

```bash
# Auto mode for complete picture
ccusage daily --mode auto --since 20260501 --until 20260516

# Calculate mode for consistent comparison
ccusage monthly --mode calculate --order asc
```

## Cost Calculation Details

### Token-Based Calculation

When calculating costs from tokens, ccusage uses:

#### Model Pricing Sources

* **LiteLLM database and models.dev catalog** - Up-to-date model pricing and model metadata
* **Automatic updates** - Pricing refreshed regularly
* **Historical schedules** - Time-varying model rates use each event's recorded timestamp
* **Multiple models** - Supports Claude Opus 4.1, Sonnet 4.5, and other models

#### Token Types

```typescript
type TokenCosts = {
	input: number; // Input tokens
	output: number; // Output tokens
	cacheCreate5m: number; // 5-minute cache creation tokens
	cacheCreate1h: number; // 1-hour cache creation tokens
	cacheRead: number; // Cache read tokens
};
```

#### Calculation Formula

```typescript
totalCost =
	inputTokens * inputPrice +
	outputTokens * outputPrice +
	cacheCreate5mTokens * cacheCreatePrice +
	cacheCreate1hTokens * inputPrice * 2 +
	cacheReadTokens * cacheReadPrice;
```

When Claude Code records do not include the `cache_creation` duration
breakdown, ccusage falls back to pricing `cache_creation_input_tokens` at the
standard cache creation rate.

### Pre-calculated Costs

Claude Code provides `costUSD` values in JSONL files:

```json
{
	"timestamp": "2026-05-16T10:30:00Z",
	"model": "claude-opus-4-1-20250805",
	"usage": {
		"input_tokens": 1245,
		"output_tokens": 28756,
		"cache_creation_input_tokens": 512,
		"cache_read_input_tokens": 256
	},
	"costUSD": 12.45
}
```

## Debug Mode

Use debug mode to understand cost calculation discrepancies:

```bash
ccusage daily --mode auto --debug
```

Shows:

* **Pricing mismatches** between calculated and pre-calculated costs
* **Missing cost data** entries
* **Calculation details** for each entry
* **Sample discrepancies** for investigation

```bash
# Show more sample discrepancies
ccusage daily --debug --debug-samples 10
```

## Mode Selection Guide

### When to use `auto` mode:

* **General usage** - Default for most scenarios
* **Mixed data sets** - Combining old and new usage data
* **Maximum accuracy** - Best available cost information
* **Regular reporting** - Daily/monthly usage tracking

### When to use `calculate` mode:

* **Consistent analysis** - Comparing different time periods
* **Token cost research** - Understanding pure token costs
* **Pricing validation** - Verifying calculated vs actual costs
* **Historical comparison** - Analyzing cost trends over time

### When to use `display` mode:

* **Billing verification** - Comparing with Claude charges
* **Official costs only** - Trusting Claude's calculations
* **Recent data analysis** - Most accurate for new usage
* **Audit purposes** - Verifying pre-calculated costs

## Advanced Usage

### Combining with Other Options

```bash
# Calculate mode with breakdown by model
ccusage daily --mode calculate --breakdown

# Display mode with JSON output for analysis
ccusage session --mode display --json | jq '.[] | select(.totalCost > 0)'

# Auto mode with date filtering
ccusage monthly --mode auto --since 20260101 --order asc
```

### Performance Considerations

* **`display` mode** - Fastest (no calculations)
* **`auto` mode** - Moderate (conditional calculations)
* **`calculate` mode** - Slowest (always calculates)

### Offline Mode Compatibility

```bash
# All modes work with offline pricing data
ccusage daily --mode calculate --offline
ccusage monthly --mode auto --offline
```

## Common Issues and Solutions

### Issue: Costs showing as $0.00

**Cause**: Using `display` mode with data that lacks pre-calculated costs

**Solution**:

```bash
# Switch to auto or calculate mode
ccusage daily --mode auto
ccusage daily --mode calculate
```

### Issue: Inconsistent cost calculations

**Cause**: Mixed use of different modes or pricing changes

**Solution**:

```bash
# Use calculate mode for consistency
ccusage daily --mode calculate --since 20260501
```

### Issue: Large discrepancies in debug mode

**Cause**: Pricing updates or model changes

**Solution**:

```bash
# Check for pricing updates
ccusage daily --mode auto  # Updates pricing cache
ccusage daily --mode calculate --debug  # Compare calculations
```

### Issue: Missing cost data for recent entries

**Cause**: Claude Code hasn't calculated costs yet

**Solution**:

```bash
# Use calculate mode as fallback
ccusage daily --mode calculate
```

## Next Steps

After understanding cost modes:

* Explore [Configuration](/guide/configuration) for environment setup
* Learn about [Claude Code](/guide/claude/) data paths for custom Claude Code directories
* Set per-model prices via [Pricing Overrides](/guide/config-files#pricing-overrides) for private or proxied models

---

---
url: /guide/json-output.md
---
# JSON Output

ccusage supports structured JSON output for all report types, making it easy to integrate with other tools, scripts, or applications that need to process usage data programmatically.

## Enabling JSON Output

Add the `--json` (or `-j`) flag to any command:

```bash
# Daily report in JSON format
ccusage daily --json

# Monthly report in JSON format
ccusage monthly --json

# Session report in JSON format
ccusage session --json

# 5-hour blocks report in JSON format
ccusage blocks --json
```

Use `--no-cost` with `--json` when reports should omit cost data:

```bash
ccusage daily --json --no-cost
ccusage blocks --json --no-cost
```

This removes cost fields such as `totalCost`, `costUSD`, `storedCost`, and nested `cost` values while keeping token, model, date, block, burn-rate, and projection fields.

## Unpriced Models

When a model has no known price, its usage is charged at `0`. Table output prints a warning on stderr; JSON output records it in the data instead, so scripts and dashboards can tell "free" from "unknown":

* `totals.unpricedModels` lists the model names, sorted and deduplicated. The key is present only when at least one entry in the report had usage with no price, so `.totals.unpricedModels // []` is safe in `jq`.
* Each affected entry in `modelBreakdowns` carries `"missingPricing": true`. Priced entries omit the key.

Both fields describe pricing availability, not amounts, so `--no-cost` keeps them.

```bash
ccusage daily --json | jq '.totals.unpricedModels // []'
```

```json
{
	"totals": {
		"inputTokens": 100488,
		"outputTokens": 3994,
		"cacheCreationTokens": 0,
		"cacheReadTokens": 50688,
		"totalTokens": 155170,
		"totalCost": 0,
		"unpricedModels": ["openrouter/auto-beta"]
	}
}
```

Detection follows the [cost mode](/guide/cost-modes): an entry counts as unpriced only when ccusage had to calculate its cost from tokens and found no price. In `display` mode, or in `auto` mode for an entry that carries its own stored cost, nothing is looked up, so nothing is reported. A model can therefore appear in `unpricedModels` and still show a positive cost when some of its entries carried stored costs. An absent key means no unpriced usage was detected under the selected mode, not that every price is current.

Covered: `daily`, `weekly`, `monthly`, and `session` reports for every agent, including `--instances`, `--sections`, and `--by-agent`. Focused `codex` reports set `missingPricing` on the affected entries of each period's `models` map. Not covered: `blocks` and `session --id`, which have no `totals` object.

Update ccusage, or run without `--offline`, once the pricing source lists the model.

Unified reports also support JSON-oriented flags for dashboard-style consumers:

```bash
ccusage daily --sections daily,monthly,session --by-agent --json
```

`--sections` emits each requested unified section from one load. The invoked command's section is always included, and the top-level `totals` object remains the total for that invoked section. JSON keys are emitted with the invoked section first, then remaining sections in `daily`, `weekly`, `monthly`, `session` order, with `totals` last. `--by-agent` adds an `agents` array to daily, weekly, and monthly rows; session rows are already per-agent.

```json
{
	"daily": [
		{
			"agent": "all",
			"agents": [
				{
					"agent": "claude",
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"inputTokens": 500,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 20,
							"cacheReadTokens": 30,
							"cost": 0.02,
							"inputTokens": 500,
							"modelName": "claude-sonnet-4-20250514",
							"outputTokens": 100
						}
					],
					"modelsUsed": ["claude-sonnet-4-20250514"],
					"outputTokens": 100,
					"totalCost": 0.02,
					"totalTokens": 650
				},
				{
					"agent": "codex",
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"inputTokens": 900,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 0,
							"cacheReadTokens": 100,
							"cost": 0.0031375,
							"inputTokens": 900,
							"modelName": "gpt-5",
							"outputTokens": 200
						}
					],
					"modelsUsed": ["gpt-5"],
					"outputTokens": 200,
					"totalCost": 0.0031375,
					"totalTokens": 1200
				}
			],
			"cacheCreationTokens": 20,
			"cacheReadTokens": 130,
			"inputTokens": 1400,
			"metadata": {
				"agents": ["claude", "codex"]
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				},
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514", "gpt-5"],
			"outputTokens": 300,
			"period": "2026-01-02",
			"totalCost": 0.023137500000000002,
			"totalTokens": 1850
		}
	],
	"monthly": [
		{
			"agent": "all",
			"agents": [
				{
					"agent": "claude",
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"inputTokens": 500,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 20,
							"cacheReadTokens": 30,
							"cost": 0.02,
							"inputTokens": 500,
							"modelName": "claude-sonnet-4-20250514",
							"outputTokens": 100
						}
					],
					"modelsUsed": ["claude-sonnet-4-20250514"],
					"outputTokens": 100,
					"totalCost": 0.02,
					"totalTokens": 650
				},
				{
					"agent": "codex",
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"inputTokens": 900,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 0,
							"cacheReadTokens": 100,
							"cost": 0.0031375,
							"inputTokens": 900,
							"modelName": "gpt-5",
							"outputTokens": 200
						}
					],
					"modelsUsed": ["gpt-5"],
					"outputTokens": 200,
					"totalCost": 0.0031375,
					"totalTokens": 1200
				}
			],
			"cacheCreationTokens": 20,
			"cacheReadTokens": 130,
			"inputTokens": 1400,
			"metadata": {
				"agents": ["claude", "codex"]
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				},
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514", "gpt-5"],
			"outputTokens": 300,
			"period": "2026-01",
			"totalCost": 0.023137500000000002,
			"totalTokens": 1850
		}
	],
	"session": [
		{
			"agent": "claude",
			"cacheCreationTokens": 20,
			"cacheReadTokens": 30,
			"inputTokens": 500,
			"metadata": {
				"lastActivity": "2026-01-02T10:00:00.000Z"
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514"],
			"outputTokens": 100,
			"period": "claude-session",
			"totalCost": 0.02,
			"totalTokens": 650
		},
		{
			"agent": "codex",
			"cacheCreationTokens": 0,
			"cacheReadTokens": 100,
			"inputTokens": 900,
			"metadata": {
				"lastActivity": "2026-01-02T11:00:00.000Z",
				"reasoningOutputTokens": 20
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["gpt-5"],
			"outputTokens": 200,
			"period": "codex-session",
			"totalCost": 0.0031375,
			"totalTokens": 1200
		}
	],
	"totals": {
		"cacheCreationTokens": 20,
		"cacheReadTokens": 130,
		"inputTokens": 1400,
		"outputTokens": 300,
		"totalCost": 0.023137500000000002,
		"totalTokens": 1850
	}
}
```

## Stored Costs

In `auto` [cost mode](/guide/cost-modes), an entry's `cost` can add together costs stored in the agent's logs (such as Claude's `costUSD`) and costs calculated from the pricing table. Each `modelBreakdowns` entry where at least one record used its stored cost carries `storedCost`, the part of `cost` that came from stored values; `cost - storedCost` is the calculated part. Entries without stored costs omit the key, and `calculate` and `display` modes never emit it.

```json
{
	"modelName": "claude-sonnet-4-20250514",
	"inputTokens": 1500,
	"outputTokens": 100,
	"cacheCreationTokens": 20,
	"cacheReadTokens": 30,
	"cost": 0.503084,
	"storedCost": 0.5
}
```

## JSON Structure

### Daily Reports (Standard)

Standard daily reports aggregate usage across all projects:

```json
{
	"daily": [
		{
			"date": "2026-05-16",
			"inputTokens": 277,
			"outputTokens": 31456,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 33269,
			"totalCost": 17.58,
			"modelsUsed": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"modelBreakdowns": [...]
		}
	],
	"totals": {
		"inputTokens": 11174,
		"outputTokens": 720366,
		"cacheCreationTokens": 896,
		"cacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCost": 336.47
	}
}
```

### Daily Reports (Project-Grouped)

When using `--instances`, daily reports group usage by project:

```json
{
	"projects": {
		"my-frontend-app": [
			{
				"date": "2026-05-16",
				"inputTokens": 177,
				"outputTokens": 16456,
				"cacheCreationTokens": 256,
				"cacheReadTokens": 512,
				"totalTokens": 17401,
				"totalCost": 7.33,
				"modelsUsed": ["claude-sonnet-4-5-20250929"],
				"modelBreakdowns": [...]
			}
		],
		"backend-api": [
			{
				"date": "2026-05-16",
				"inputTokens": 100,
				"outputTokens": 15000,
				"cacheCreationTokens": 256,
				"cacheReadTokens": 512,
				"totalTokens": 15868,
				"totalCost": 10.25,
				"modelsUsed": ["claude-opus-4-1-20250805"],
				"modelBreakdowns": [...]
			}
		]
	},
	"totals": {
		"inputTokens": 277,
		"outputTokens": 31456,
		"cacheCreationTokens": 512,
		"cacheReadTokens": 1024,
		"totalTokens": 33269,
		"totalCost": 17.58
	}
}
```

#### Usage

```bash
# Standard aggregated output
ccusage daily --json

# Project-grouped output
ccusage daily --instances --json

# Filter to specific project
ccusage daily --project my-frontend-app --json
```

### Monthly Reports

```json
{
	"type": "monthly",
	"data": [
		{
			"month": "2026-04",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 11174,
			"outputTokens": 720366,
			"cacheCreationTokens": 896,
			"cacheReadTokens": 2304,
			"totalTokens": 734740,
			"costUSD": 336.47
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720366,
		"totalCacheCreationTokens": 896,
		"totalCacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCostUSD": 336.47
	}
}
```

### Session Reports

```json
{
	"type": "session",
	"data": [
		{
			"session": "session-1",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 4512,
			"outputTokens": 350846,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 356894,
			"costUSD": 156.4,
			"firstActivity": "2026-05-15T09:30:00.000Z",
			"lastActivity": "2026-05-15T17:45:30.000Z"
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720445,
		"totalCacheCreationTokens": 768,
		"totalCacheReadTokens": 1792,
		"totalTokens": 734179,
		"totalCostUSD": 336.68
	}
}
```

### Blocks Reports

```json
{
	"type": "blocks",
	"data": [
		{
			"blockStart": "2026-05-16T10:00:00.000Z",
			"blockEnd": "2026-05-16T15:00:00.000Z",
			"isActive": true,
			"timeRemaining": "2h 15m",
			"models": ["claude-sonnet-4-5-20250929"],
			"inputTokens": 1250,
			"outputTokens": 15000,
			"cacheCreationTokens": 256,
			"cacheReadTokens": 512,
			"totalTokens": 17018,
			"costUSD": 8.75,
			"burnRate": 2400,
			"projectedTotal": 25000,
			"projectedCost": 12.5
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720366,
		"totalCacheCreationTokens": 896,
		"totalCacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCostUSD": 336.47
	}
}
```

## Field Descriptions

### Common Fields

* `models`: Array of Claude model names used
* `inputTokens`: Number of input tokens consumed
* `outputTokens`: Number of output tokens generated
* `cacheCreationTokens`: Tokens used for cache creation
* `cacheReadTokens`: Tokens read from cache
* `totalTokens`: Sum of all token types
* `costUSD`: Estimated cost in US dollars

### Report-Specific Fields

#### Daily Reports

* `date`: Date in YYYY-MM-DD format

#### Monthly Reports

* `month`: Month in YYYY-MM format

#### Session Reports

* `session`: Session identifier
* `firstActivity`: RFC 3339 timestamp of first activity in the session
* `lastActivity`: RFC 3339 timestamp of last activity in the session

#### Blocks Reports

* `blockStart`: ISO timestamp of block start
* `blockEnd`: ISO timestamp of block end
* `isActive`: Whether the block is currently active
* `timeRemaining`: Human-readable time remaining (active blocks only)
* `burnRate`: Tokens per hour rate (active blocks only)
* `projectedTotal`: Projected total tokens for the block
* `projectedCost`: Projected total cost for the block

## Filtering with JSON Output

All filtering options work with JSON output:

```bash
# Filter by date range
ccusage daily --json --since 20260510 --until 20260516

# Different cost calculation modes
ccusage monthly --json --mode calculate
ccusage session --json --mode display

# Sort order
ccusage daily --json --order asc

# With model breakdown
ccusage daily --json --breakdown

# Hide cost fields
ccusage daily --json --no-cost

# Project analysis
ccusage daily --json --instances                    # Group by project
ccusage daily --json --project my-project           # Filter to project
ccusage daily --json --instances --project my-app   # Combined usage
```

### Model Breakdown JSON

When using `--breakdown`, the JSON includes per-model details:

```json
{
	"type": "daily",
	"data": [
		{
			"date": "2026-05-16",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 277,
			"outputTokens": 31456,
			"totalTokens": 33269,
			"costUSD": 17.58,
			"breakdown": {
				"claude-opus-4-1-20250805": {
					"inputTokens": 100,
					"outputTokens": 15000,
					"cacheCreationTokens": 256,
					"cacheReadTokens": 512,
					"totalTokens": 15868,
					"costUSD": 10.25
				},
				"claude-sonnet-4-5-20250929": {
					"inputTokens": 177,
					"outputTokens": 16456,
					"cacheCreationTokens": 256,
					"cacheReadTokens": 512,
					"totalTokens": 17401,
					"costUSD": 7.33
				}
			}
		}
	]
}
```

## Integration Examples

### Using with jq

You can pipe JSON output to jq for advanced filtering and formatting:

```bash
# Get total cost for the last 7 days
ccusage daily --json --since $(date -d '7 days ago' +%Y%m%d) | jq '.summary.totalCostUSD'

# List all unique models used
ccusage session --json | jq -r '.data[].models[]' | sort -u

# Find the most expensive session
ccusage session --json | jq -r '.data | sort_by(.costUSD) | reverse | .[0].session'

# Get daily costs as CSV
ccusage daily --json | jq -r '.daily[] | [.date, .totalCost] | @csv'

# Analyze project costs
ccusage daily --instances --json | jq -r '.projects | to_entries[] | [.key, (.value | map(.totalCost) | add)] | @csv'

# Find most expensive project
ccusage daily --instances --json | jq -r '.projects | to_entries | map({project: .key, total: (.value | map(.totalCost) | add)}) | sort_by(.total) | reverse | .[0].project'

# Get usage by project for specific date
ccusage daily --instances --json | jq '.projects | to_entries[] | select(.value[].date == "2026-05-16") | {project: .key, usage: .value[0]}'
```

### Using with Python

```python
import json
import subprocess

# Get daily usage data
result = subprocess.run(['ccusage', 'daily', '--json'], capture_output=True, text=True)
data = json.loads(result.stdout)

# Process the data
for day in data['data']:
    print(f"Date: {day['date']}, Cost: ${day['costUSD']:.2f}")

total_cost = data['totals']['totalCost']
print(f"Total cost: ${total_cost:.2f}")

# Project analysis example
result = subprocess.run(['ccusage', 'daily', '--instances', '--json'], capture_output=True, text=True)
project_data = json.loads(result.stdout)

if 'projects' in project_data:
    for project_name, daily_entries in project_data['projects'].items():
        project_total = sum(day['totalCost'] for day in daily_entries)
        print(f"Project {project_name}: ${project_total:.2f}")

    # Find highest spending project
    project_totals = {
        project: sum(day['totalCost'] for day in days)
        for project, days in project_data['projects'].items()
    }
    top_project = max(project_totals, key=project_totals.get)
    print(f"Highest spending project: {top_project} (${project_totals[top_project]:.2f})")
```

### Using with Node.js

```javascript
import { execSync } from 'node:child_process';

// Get session usage data
const output = execSync('ccusage session --json', { encoding: 'utf-8' });
const data = JSON.parse(output);

// Find sessions over $10
const expensiveSessions = data.data.filter((session) => session.costUSD > 10);
console.log(`Found ${expensiveSessions.length} expensive sessions`);

expensiveSessions.forEach((session) => {
	console.log(`${session.session}: $${session.costUSD.toFixed(2)}`);
});

// Project analysis example
const projectOutput = execSync('ccusage daily --instances --json', { encoding: 'utf-8' });
const projectData = JSON.parse(projectOutput);

if (projectData.projects) {
	// Calculate total cost per project
	const projectCosts = Object.entries(projectData.projects).map(([name, days]) => ({
		name,
		totalCost: days.reduce((sum, day) => sum + day.totalCost, 0),
		totalTokens: days.reduce((sum, day) => sum + day.totalTokens, 0),
	}));

	// Sort by cost descending
	projectCosts.sort((a, b) => b.totalCost - a.totalCost);

	console.log('Project Usage Summary:');
	projectCosts.forEach((project) => {
		console.log(
			`${project.name}: $${project.totalCost.toFixed(2)} (${project.totalTokens.toLocaleString()} tokens)`,
		);
	});
}
```

## Programmatic Usage

JSON output is designed for programmatic consumption:

* **Consistent structure**: All fields are always present (with 0 or empty values when not applicable)
* **Standard types**: Numbers for metrics, strings for identifiers, arrays for lists
* **ISO timestamps**: Standardized date/time formats for reliable parsing
* **Stable schema**: Field names and structures remain consistent across versions

---

---
url: /guide/community-projects.md
---
# Community Projects

Community projects built around ccusage, Claude Code usage tracking, or related workflows.

These projects are maintained independently and are not affiliated with the ccusage project or ryoppippi.

## Desktop Applications

* [claude-usage-tracker-for-mac](https://github.com/penicillin0/claude-usage-tracker-for-mac) - macOS menu bar app for tracking Claude usage
* [ClaudeCode_Dashboard](https://github.com/m-sigepon/ClaudeCode_Dashboard) - Web dashboard with charts and visualizations
* [Ccusage App](https://github.com/EthanBarlo/ccusage-app) - Native application to display ccusage data in graphs and visualizations
* [CCOwl](https://github.com/sivchari/ccowl) - A cross-platform status bar application that monitors Claude Code usage in real-time.
* [ccx](https://github.com/aaronwong1999/ccx) - macOS menu bar app that continues a Claude Code session in Codex (and back) with its full context; reads `ccusage blocks --json` to warn when the current 5-hour block is on pace to pass your largest one

## Extensions & Integrations

* [ccusage Raycast Extension](https://www.raycast.com/nyatinte/ccusage) - Raycast integration for quick usage checks
* [ccusage.nvim](https://github.com/S1M0N38/ccusage.nvim) - Track Claude Code usage in Neovim

## CLI Utilities

* [scx](https://github.com/yamamuteki/scx) - Convert ccusage USD output from stdin into a local currency
* [cachemiss](https://github.com/CedricConday/cachemiss) - Lists every prompt-cache rebuild in your Claude Code transcripts with its reason (from `message.diagnostics.cache_miss_reason` when the field is present, otherwise inferred and marked as such), the tokens rewritten, and the write premium over a cache read, per session, agent, and model

## Web Applications

* [Straude](https://straude.com) - Strava-style Claude Code telemetry for logging usage, tracking spend, and comparing pace
* [viberank](https://viberank.app) - A community-driven leaderboard for Claude Code usage. ([GitHub](https://github.com/sculptdotfun/viberank))
* [CCWarriors](https://ccwarriors.xyz) - Live leaderboard of AI coding spend across Claude Code, Codex, Gemini, and other ccusage-readable agents, with per-tool filters and real-time updates. ([GitHub](https://github.com/distroinfinity/ccwarriors))
* [Token Battle](https://tokenbattle.vercel.app) - AI coding cost leaderboard for comparing monthly ccusage exports from Claude Code, Codex CLI, and Gemini CLI, with dashboard uploads, public rankings, and shareable profiles.
* [TokenNations](https://tokennations.app) - Country-vs-country leaderboard for AI coding usage. The CLI reads Claude Code, Codex, Gemini CLI, and other ccusage-readable agents locally and syncs only token counts.

## Contributing

If you've built something that uses ccusage, please feel free to open a pull request to add it to this list!

---

---
url: /guide/sponsors.md
---
# Sponsors

ccusage is sponsored by CodeRabbit and Blacksmith.

## How to Sponsor

Visit [GitHub Sponsors - @ryoppippi](https://github.com/sponsors/ryoppippi) to support the development of ccusage and other open source projects.

## Star History

---

---
url: /AGENTS.md
---
# AGENTS.md - Documentation

`README.md` covers the site structure, hosting, and commands. This file adds the writing
conventions for changes under `docs/`.

* A guide with a primary screenshot leads with it, immediately after the H1, with descriptive alt
  text and a root-relative path such as `/screenshot.png` for files in `docs/public/`. See
  `guide/daily-reports.md`.
* Cross-link related guides and `guide/json-output.md` where useful.
* Put `<!-- eslint-skip -->` before a markdown code block ESLint should skip.

---

---
url: /guide/blocks-reports.md
---
# Blocks

Blocks reports show your Claude Code usage grouped by 5-hour billing windows, helping you understand Claude's billing cycle and track active session progress.

## Basic Usage

```bash
ccusage blocks
```

## Example Output

```
╭──────────────────────────────────────────────────╮
│                                                  │
│  Claude Code Token Usage Report - Session Blocks │
│                                                  │
╰──────────────────────────────────────────────────╯

┌─────────────────────┬────────────────────┬────────┬─────────┬──────────────┬────────────┬──────────────┬────────────┐
│ Block Start Time    │ Models             │ Input  │ Output  │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
├─────────────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-16 09:00:00 │ • opus-4-1         │  4,512 │ 285,846 │          512 │      1,024 │      291,894 │    $156.40 │
│ ⏰ Active (2h 15m)  │ • sonnet-4-5       │        │         │              │            │              │            │
│ 🔥 Rate: 2.1k/min   │                  │        │         │              │            │              │            │
│ 📊 Projected: 450k  │                  │        │         │              │            │              │            │
├─────────────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-16 04:00:00 │ • sonnet-4-5       │  2,775 │ 186,645 │          256 │        768 │      190,444 │     $98.45 │
│ ✅ Completed (3h 42m)│                  │        │         │              │            │              │            │
├─────────────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ 2026-05-15 15:30:00 │ • opus-4-1         │  1,887 │ 183,055 │          128 │        512 │      185,582 │     $81.73 │
│ ✅ Completed (4h 12m)│                  │        │         │              │            │              │            │
├─────────────────────┼────────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┤
│ Total               │                  │  9,174 │ 655,546 │          896 │      2,304 │      667,920 │    $336.58 │
└─────────────────────┴────────────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┘
```

## Understanding Blocks

### Session Block Concept

Claude Code uses **5-hour billing windows** for session tracking:

* **Block Start**: Triggered by your first message
* **Block Duration**: Lasts exactly 5 hours from start time
* **Rolling Windows**: New blocks start with activity after previous block expires
* **Billing Relevance**: Matches Claude's internal session tracking
* **UTC Time Handling**: Block boundaries are calculated in UTC to ensure consistent behavior across time zones

### Block Status Indicators

* **⏰ Active**: Currently running block with time remaining
* **✅ Completed**: Finished block that ran its full duration or ended naturally
* **⌛ Gap**: Time periods with no activity (shown when relevant)
* **🔥 Rate**: Token burn rate (tokens per minute) for active blocks
* **📊 Projected**: Estimated total tokens if current rate continues

## Command Options

### Show Active Block Only

Focus on your current session with detailed projections:

```bash
ccusage blocks --active
```

This shows only the currently active block with:

* Time remaining in the 5-hour window
* Current token burn rate
* Projected final token count and cost

### Show Recent Blocks

Display blocks from the last 3 days (including active):

```bash
ccusage blocks --recent
```

Perfect for understanding recent usage patterns without scrolling through all historical data.

### Token Limit Tracking

Set token limits to monitor quota usage:

```bash
# Set explicit token limit
ccusage blocks --token-limit 500000

# Use highest previous block as limit
ccusage blocks --token-limit max
# or short form:
ccusage blocks -t max
```

When limits are set, blocks display:

* ⚠️ **Warning indicators** when approaching limits
* 🚨 **Alert indicators** when exceeding limits
* **Progress bars** showing usage relative to limit

### Live Monitoring (Removed)

::: danger REMOVED IN v18
The `blocks --live` monitor feature has been removed in v18.0.0. This feature is available in v17.x. Please use the [statusline command](/guide/statusline) instead for real-time monitoring.
:::

Previously available options (v17.x only):

```bash
# Basic live monitoring (uses -t max automatically)
ccusage blocks --live

# Live monitoring with explicit token limit
ccusage blocks --live --token-limit 500000

# Custom refresh interval (1-60 seconds)
ccusage blocks --live --refresh-interval 5
```

### Custom Session Duration

Change the block duration (default is 5 hours):

```bash
# 3-hour blocks
ccusage blocks --session-length 3

# 8-hour blocks
ccusage blocks --session-length 8
```

### Date Filtering

Filter blocks by date range:

```bash
# Show blocks from specific date range
ccusage blocks --since 20260515 --until 20260516

# Show blocks from last week
ccusage blocks --since $(date -d '7 days ago' +%Y%m%d)
```

### Sort Order

```bash
# Show newest blocks first (default)
ccusage blocks --order desc

# Show oldest blocks first
ccusage blocks --order asc
```

### Cost Calculation Modes

```bash
# Use pre-calculated costs when available (default)
ccusage blocks --mode auto

# Always calculate costs from tokens
ccusage blocks --mode calculate

# Only show pre-calculated costs
ccusage blocks --mode display
```

### JSON Output

Export block data for analysis:

```bash
ccusage blocks --json
```

```json
{
	"blocks": [
		{
			"id": "2026-05-16T09:00:00.000Z",
			"startTime": "2026-05-16T09:00:00.000Z",
			"endTime": "2026-05-16T14:00:00.000Z",
			"actualEndTime": "2026-05-16T11:15:00.000Z",
			"isActive": true,
			"tokenCounts": {
				"inputTokens": 4512,
				"outputTokens": 285846,
				"cacheCreationInputTokens": 512,
				"cacheReadInputTokens": 1024
			},
			"costUSD": 156.4,
			"models": ["opus-4-1", "sonnet-4-5"]
		}
	]
}
```

### Offline Mode

Use cached pricing data without network access:

```bash
ccusage blocks --offline
# or short form:
ccusage blocks -O
```

## Analysis Use Cases

### Session Planning

Understanding 5-hour windows helps with:

```bash
# Check current active block
ccusage blocks --active
```

* **Time Management**: Know how much time remains in current session
* **Usage Pacing**: Monitor if you're on track for reasonable usage
* **Break Planning**: Understand when current session will expire

### Usage Optimization

```bash
# Find your highest usage patterns
ccusage blocks -t max --recent
```

* **Peak Usage Identification**: Which blocks consumed the most tokens
* **Efficiency Patterns**: Compare block efficiency (tokens per hour)
* **Model Selection Impact**: How model choice affects block costs

### Real-time Session Tracking

```bash
# Monitor active sessions in real-time
ccusage statusline
```

Perfect for:

* **Long coding sessions**: Track progress against historical limits
* **Budget management**: Watch costs accumulate in real-time
* **Productivity tracking**: Understand work intensity patterns

### Historical Analysis

```bash
# Export data for detailed analysis
ccusage blocks --json > blocks-history.json

# Analyze patterns over time
ccusage blocks --since 20260501 --until 20260531
```

## Block Analysis Tips

### 1. Understanding Block Efficiency

Look for patterns in your block data:

* **High-efficiency blocks**: Lots of output tokens for minimal input
* **Exploratory blocks**: High input/output ratios (research, debugging)
* **Focused blocks**: Steady token burn rates with clear objectives

### 2. Time Management

Use blocks to optimize your Claude usage:

* **Session planning**: Start important work at the beginning of blocks
* **Break timing**: Use block boundaries for natural work breaks
* **Batch processing**: Group similar tasks within single blocks

### 3. Cost Optimization

Blocks help identify cost patterns:

* **Model switching**: When to use Opus 4.1 vs Sonnet 4.5 within blocks
* **Cache efficiency**: How cache usage affects block costs
* **Usage intensity**: Whether short focused sessions or long exploratory ones are more cost-effective

### 4. Quota Management

When working with token limits:

* **Rate monitoring**: Watch burn rates to avoid exceeding limits
* **Early warning**: Set limits below actual quotas for safety margin
* **Usage spreading**: Distribute heavy usage across multiple blocks

## Responsive Display

Blocks reports adapt to your terminal width:

* **Wide terminals (≥100 chars)**: Shows all columns with full timestamps
* **Narrow terminals (<100 chars)**: Compact mode with abbreviated times and essential data

## Advanced Features

### Gap Detection

Blocks reports automatically detect and display gaps:

```
┌─────────────────────┬────────────────────┬────────┬─────────┬────────────┐
│ 2026-05-16 09:00:00 │ • opus-4-1         │  4,512 │ 285,846 │    $156.40 │
│ ⏰ Active (2h 15m)  │ • sonnet-4-5       │        │         │            │
├─────────────────────┼────────────────────┼────────┼─────────┼────────────┤
│ 2026-05-15 22:00:00 │ ⌛ 11h gap       │      0 │       0 │      $0.00 │
│ 2026-05-16 09:00:00 │                  │        │         │            │
├─────────────────────┼────────────────────┼────────┼─────────┼────────────┤
│ 2026-05-15 15:30:00 │ • opus-4-1         │  1,887 │ 183,055 │     $81.73 │
│ ✅ Completed (4h 12m)│                  │        │         │            │
└─────────────────────┴────────────────────┴────────┴─────────┴────────────┘
```

### Burn Rate Calculations

For active blocks, the tool calculates:

* **Tokens per minute**: Based on activity within the block
* **Cost per hour**: Projected hourly spend rate
* **Projected totals**: Estimated final tokens/cost if current rate continues

### Progress Visualization

When using token limits, blocks show visual progress:

* **Green**: Usage well below limit (< 70%)
* **Yellow**: Approaching limit (70-90%)
* **Red**: At or exceeding limit (≥ 90%)

## Related Commands

* [Daily Usage](/guide/daily-reports) - Usage aggregated by calendar date
* [Monthly Usage](/guide/monthly-reports) - Monthly usage summaries
* [Session Usage](/guide/session-reports) - Individual conversation analysis
* [Statusline](/guide/statusline) - Real-time session tracking (replacement for live monitoring)

## Next Steps

After understanding block patterns, consider:

1. [Statusline](/guide/statusline) for real-time active session tracking
2. [Session Usage](/guide/session-reports) to analyze individual conversations within blocks
3. [Daily Usage](/guide/daily-reports) to see how blocks aggregate across days

---

---
url: /README.md
---
# Documentation Site

This directory contains the VitePress documentation website for ccusage.

The public site is hosted on Cloudflare at https://ccusage.com.

## Structure

* `guide/` - user guides and tutorials.
* `public/` - screenshots, static assets, and generated config schema.
* `.vitepress/` - VitePress configuration and theme customization.

The docs build copies `apps/ccusage/config-schema.json` to
`docs/public/config-schema.json` before running VitePress.

## Commands

```sh
just docs::dev
just docs::build
just docs::preview
just docs::typecheck
just fmt
```

---

---
url: /superpowers/specs/2026-07-28-grok-env-only-path-design.md
---
# Grok Env-Only Path Discovery Design

## Context

The Grok adapter currently exposes an explicit path through `--grok-path`,
`grokPath`, and internal command/config plumbing. Carrying that value into every
report path also led to a change where a bare `ccusage` invocation is parsed as
an explicit unified daily command instead of retaining the existing
`command: None` representation.

Other adapters do not establish one universal path-configuration pattern. Pi
supports an explicit focused-command path, while Gemini discovers its data
directory from an environment variable or a default location. Grok only needs
one data root and does not need a second ccusage-specific override mechanism.

## Decision

The Grok adapter will resolve its home directory using this precedence:

1. A non-empty `GROK_HOME` environment variable.
2. The default `~/.grok` directory.

There will be no `--grok-path` CLI option, `grokPath` configuration property,
`CCUSAGE_GROK_PATH` variable, or internal Grok path argument. Focused Grok
reports and all unified report entry points will use the same adapter-owned
discovery logic.

The `grok` configuration namespace remains available for shared report options,
such as JSON or offline behavior, just as other agent namespaces are.

## Data Flow

For `ccusage grok`, explicit `ccusage all` commands, bare `ccusage`, and unified
session reports, command handling selects the Grok adapter without supplying a
path. The adapter reads `GROK_HOME`; after rejecting an empty value, it falls
back to `~/.grok`, then loads the adapter's expected session data beneath that
root.

Because no path value needs to be injected into the default command, bare
`ccusage` parsing returns `command: None` as it did before Grok support. The
existing application entry point remains responsible for interpreting that as
the unified daily report.

## Required Changes

* Remove `--grok-path` and its help text and snapshots.
* Remove `grokPath` from configuration types, generated schema, examples, and
  tests.
* Remove the Grok path field from agent command arguments and from focused and
  unified loader plumbing.
* Remove any remaining `CCUSAGE_GROK_PATH` handling or regression references.
* Keep only `GROK_HOME` and `~/.grok` resolution in the Grok adapter.
* Restore the pre-feature bare-command parser representation.

## Validation

Tests will verify that:

* a non-empty `GROK_HOME` selects that directory;
* an unset or empty `GROK_HOME` falls back to `~/.grok`;
* focused, explicit unified, bare unified daily, and unified session reports can
  load Grok data through the same discovery path;
* bare parsing again yields no explicit command;
* generated configuration schema, CLI help, and snapshots contain neither
  `grokPath` nor `--grok-path`;
* existing workspace formatting, tests, and lint checks continue to pass.

Environment-mutating tests must use the repository's environment guard pattern
so their state is restored and they do not race with unrelated tests.

## Documentation Impact

User-facing documentation will describe `GROK_HOME` and the `~/.grok` default.
Any mention of `grokPath` or `--grok-path` introduced by this feature will be
removed. The generated configuration schema will be regenerated from the
updated configuration types.

## Out of Scope

* Changing Pi, Gemini, or other adapters' path behavior.
* Introducing a generalized path configuration abstraction.
* Supporting multiple Grok roots.
* Adding another Grok-specific environment variable.
* Refactoring unrelated unified report or configuration behavior.

## Compatibility

The Grok feature has not been merged or released, so removing its provisional
path option and configuration property does not require a deprecation period or
backward-compatibility shim.

---

---
url: /guide/live-monitoring.md
---
# Live Monitoring (Removed)

![Live monitoring dashboard showing real-time token usage, burn rate, and cost projections](/blocks-live.png)

::: danger REMOVED IN v18
The `blocks --live` monitor feature has been removed in v18.0.0. This feature is available in v17.x.
:::

## Historical Reference (v17.x)

The following documentation is preserved for users on v17.x.

### Quick Start

```bash
ccusage blocks --live
```

This starts live monitoring with automatic token limit detection based on your usage history.

### Features

#### Real-time Updates

The dashboard refreshes every second, showing:

* **Current session progress** with visual progress bar
* **Token burn rate** (tokens per minute)
* **Time remaining** in current 5-hour block
* **Cost projections** based on current usage patterns
* **Quota warnings** with color-coded alerts

### Command Options

#### Token Limits

Set custom token limits for quota warnings:

```bash
# Use specific token limit
ccusage blocks --live -t 500000

# Use highest previous session as limit (default)
ccusage blocks --live -t max
```

#### Refresh Interval

Control update frequency:

```bash
# Update every 5 seconds
ccusage blocks --live --refresh-interval 5

# Update every 10 seconds (lighter on CPU)
ccusage blocks --live --refresh-interval 10
```

### Keyboard Controls

While live monitoring is active:

* **Ctrl+C**: Exit monitoring gracefully
* **Terminal resize**: Automatically adjusts display

## Related Commands

* [Blocks](/guide/blocks-reports) - Static 5-hour block analysis
* [Session Usage](/guide/session-reports) - Historical session data
* [Daily Usage](/guide/daily-reports) - Day-by-day usage patterns

---

---
url: /guide/statusline.md
---
# Statusline Integration (Beta) 🚀

Display real-time usage statistics in your Claude Code status line.

## Overview

The `statusline` command provides a compact, real-time view of your Claude Code usage, designed to integrate with Claude Code's status line hooks. It shows:

* 💬 **Current session cost** - Cost for your active conversation session
* 💰 **Today's total cost** - Your cumulative spending for the current day
* 🚀 **Current session block** - Cost and time remaining in your active 5-hour billing block
* 🔥 **Burn rate** - Token consumption rate with visual indicators
* 🤖 **Active model** - The Claude model you're currently using, with its reasoning effort level when available

## Setup

### Configure settings.json

Add this to your `~/.claude/settings.json` or `~/.config/claude/settings.json`:

::: code-group

```json [bun x (Recommended)]
{
	"statusLine": {
		"type": "command",
		"command": "bun x ccusage statusline",
		"padding": 0
	}
}
```

```json [claude x]
{
	"statusLine": {
		"type": "command",
		"command": "BUN_BE_BUN=1 claude x ccusage statusline",
		"padding": 0
	}
}
```

```json [npx]
{
	"statusLine": {
		"type": "command",
		"command": "npx -y ccusage statusline",
		"padding": 0
	}
}
```

:::

::: tip claude x option
The `claude x` option requires the native version of Claude Code (not the npm version). If you installed Claude Code via npm, use the `bun x` or `npx` options instead.
:::

By default, statusline uses **offline mode** with cached pricing data for optimal performance.

### Online Mode (Optional)

If you need the latest pricing data from LiteLLM API, you can explicitly enable online mode:

```json
{
	"statusLine": {
		"type": "command",
		"command": "bun x ccusage statusline --no-offline", // Fetches latest pricing from API
		"padding": 0
	}
}
```

### With Visual Burn Rate (Optional)

You can enhance the burn rate display with visual indicators:

```json
{
	"statusLine": {
		"type": "command",
		"command": "bun x ccusage statusline --visual-burn-rate emoji", // Add emoji indicators
		"padding": 0
	}
}
```

See [Visual Burn Rate](#visual-burn-rate) section for all available options.

### With Cost Source Options (Optional)

You can control how session costs are calculated and displayed:

```json
{
	"statusLine": {
		"type": "command",
		"command": "bun x ccusage statusline --cost-source both", // Show both CC and ccusage costs
		"padding": 0
	}
}
```

See [Cost Source Options](#cost-source-options) section for all available modes.

## Output Format

The statusline displays a compact, single-line summary:

```text
🤖 Fable 5 (high) | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
```

When using `--cost-source both`, the session cost shows both Claude Code and ccusage calculations:

```text
🤖 Fable 5 (high) | 💰 ($0.25 cc / $0.23 ccusage) session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
```

The reasoning effort level next to the model name comes from Claude Code (2.1.119+). All current Claude models report it; for older Claude Code versions or models without the effort parameter, the statusline shows just the model name:

```text
🤖 Opus 4.1 | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
```

### Components Explained

* **Model** (`🤖 Fable 5 (high)`): Currently active Claude model, followed by the reasoning effort level in parentheses (`low`, `medium`, `high`, `xhigh`, or `max`) when Claude Code provides it
* **Session Cost** (`💰 $0.23 session`): Cost for the current conversation session (see [Cost Source Options](#cost-source-options) for different calculation modes)
* **Today's Cost** (`$1.23 today`): Total cost for the current day across all sessions
* **Session Block** (`$0.45 block (2h 45m left)`): Current 5-hour block cost with remaining time
* **Burn Rate** (`🔥 $0.12/hr`): Cost burn rate per hour with color-coded indicators:
  * Green text: Normal (< 2,000 tokens/min)
  * Yellow text: Moderate (2,000-5,000 tokens/min)
  * Red text: High (> 5,000 tokens/min)
  * Optional visual status indicators (see [Visual Burn Rate](#visual-burn-rate))
* **Context Usage** (`🧠 25,000 (12%)`): Shows input tokens with percentage of context limit:
  * Green text: Low usage (< 50% by default)
  * Yellow text: Medium usage (50-80% by default)
  * Red text: High usage (> 80% by default)
  * Uses Claude Code's [`context_window` data](https://code.claude.com/docs/en/statusline) when available for accurate token counts

When no active block exists:

```text
🤖 Fable 5 (high) | 💰 $0.00 session / $0.00 today / No active block
```

## Technical Details

The statusline command:

* Reads session information from stdin (provided by Claude Code hooks)
* Identifies the active 5-hour billing block
* Calculates real-time burn rates and projections
* Outputs a single line suitable for status bar display
* **Uses offline mode by default** for instant response times without network dependencies
* Can be configured to use online mode with `--no-offline` for latest pricing data

## Beta Notice

⚠️ This feature is currently in **beta**. More customization options and features are coming soon:

* Custom format templates
* Configurable burn rate thresholds
* Additional metrics display options
* Session-specific cost tracking

### Cost Source Options

The `--cost-source` option controls how session costs are calculated and displayed:

**Available modes:**

* `auto` (default): Prefer Claude Code's pre-calculated cost when available, fallback to ccusage calculation
* `ccusage`: Always calculate costs using ccusage's token-based calculation with LiteLLM pricing
* `cc`: Always use Claude Code's pre-calculated cost from session data
* `both`: Display both Claude Code and ccusage costs side by side for comparison

**Command-line usage:**

```bash
# Default auto mode
bun x ccusage statusline

# Always use ccusage calculation
bun x ccusage statusline --cost-source ccusage

# Always use Claude Code cost
bun x ccusage statusline --cost-source cc

# Show both costs for comparison
bun x ccusage statusline --cost-source both
```

**Settings.json configuration:**

```json
{
	"statusLine": {
		"type": "command",
		"command": "bun x ccusage statusline --cost-source both",
		"padding": 0
	}
}
```

**When to use each mode:**

* **`auto`**: Best for most users, provides accurate costs with fallback reliability
* **`ccusage`**: When you want consistent calculation methods across all ccusage commands
* **`cc`**: When you trust Claude Code's cost calculations and want minimal processing
* **`both`**: For debugging cost discrepancies or comparing calculation methods

**Output differences:**

* **Single cost modes** (`auto`, `ccusage`, `cc`): `💰 $0.23 session`
* **Both mode**: `💰 ($0.25 cc / $0.23 ccusage) session`

## Configuration

### Context Usage Thresholds

You can customize the context usage color thresholds using command-line options or configuration files:

* `--context-low-threshold` - Percentage below which context usage is shown in green (default: 50)
* `--context-medium-threshold` - Percentage below which context usage is shown in yellow (default: 80)

**Validation and Safety Features:**

* Values are automatically validated to be integers in the 0-100 range
* The `LOW` threshold must be less than the `MEDIUM` threshold
* Invalid configurations will show clear error messages

**Command-line usage:**

```bash
bun x ccusage statusline --context-low-threshold 60 --context-medium-threshold 90
```

**Configuration file usage:**
You can also set these options in your configuration file. See the [Configuration Guide](/guide/configuration) for more details.

With these settings:

* Green: < 60%
* Yellow: 60-90%
* Red: > 90%

**Example usage in Claude Code settings:**

```json
{
	"command": "bun x ccusage statusline --context-low-threshold 60 --context-medium-threshold 90",
	"timeout": 5000
}
```

### Visual Burn Rate

You can enhance the burn rate display with visual status indicators using the `--visual-burn-rate` option:

```bash
# Add to your settings.json command
bun x ccusage statusline --visual-burn-rate emoji
```

**Available options:**

* `off` (default): No visual indicators, only colored text
* `emoji`: Add emoji indicators (🟢/⚠️/🚨)
* `text`: Add text status in parentheses (Normal/Moderate/High)
* `emoji-text`: Combine both emoji and text indicators

**Examples:**

```bash
# Default (off)
🔥 $0.12/hr

# With emoji
🔥 $0.12/hr 🟢

# With text
🔥 $0.12/hr (Normal)

# With both emoji and text
🔥 $0.12/hr 🟢 (Normal)
```

**Status Indicators:**

* 🟢 Normal (Green)
* ⚠️ Moderate (Yellow)
* 🚨 High (Red)

### Model Label Aliases

Some setups report very long model identifiers. For example, AWS Bedrock
inference profiles surface full ARNs such as
`arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345`,
which gets truncated in the statusline and hides which model is in use.

Use `modelLabelAliases` in your configuration file to map a model identifier to
a short display label. When the active model matches a key, the statusline shows
the alias instead:

```json
{
	"commands": {
		"statusline": {
			"modelLabelAliases": {
				"arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345": "claude-opus-4-6"
			}
		}
	}
}
```

With the alias above, the statusline changes from:

```text
🤖 arn:aws:bedrock:ap-northeast-1:012345678910:application-inference-profile/abcde12345 | 💰 ...
```

to:

```text
🤖 claude-opus-4-6 | 💰 ...
```

Keys are matched exactly against the model's display name. Models without a
matching alias are shown unchanged. See the [Configuration Guide](/guide/configuration)
for more details.

## Troubleshooting

### No Output Displayed

If the statusline doesn't show:

1. Verify `ccusage` is in your PATH
2. Check Claude Code logs for any errors
3. Ensure you have valid usage data in your Claude data directory

### Incorrect Costs

If costs seem incorrect:

* The command uses the same cost calculation as other ccusage commands
* Verify with `ccusage daily` or `ccusage blocks` for detailed breakdowns

## Related Commands

* [`blocks`](./blocks-reports.md) - Detailed 5-hour billing block analysis
* [`daily`](./daily-reports.md) - Daily usage reports
* [`session`](./session-reports.md) - Session-based usage analysis