--- 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 ` 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).