# ccusage

**Repository Path**: mirrors_trending/ccusage

## Basic Information

- **Project Name**: ccusage
- **Description**: A CLI tool for analyzing Claude Code usage from local JSONL files.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-16
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
    <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.svg" alt="ccusage logo" width="256" height="256">
    <h1>ccusage</h1>
</div>

<p align="center">
    <a href="https://socket.dev/npm/package/ccusage"><img src="https://socket.dev/api/badge/npm/package/ccusage" alt="Socket Badge" /></a>
    <a href="https://npmjs.com/package/ccusage"><img src="https://img.shields.io/npm/v/ccusage?color=yellow" alt="npm version" /></a>
    <a href="https://tanstack.com/stats/npm?packageGroups=%5B%7B%22packages%22:%5B%7B%22name%22:%22ccusage%22%7D%5D%7D%5D&range=30-days&transform=none&binType=daily&showDataMode=all&height=400"><img src="https://img.shields.io/npm/dt/ccusage" alt="NPM Downloads" /></a>
    <a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki"></a>
    <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
    <a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code" /></a>
</p>

<p align="center">
    <a href="https://trendshift.io/repositories/18533" target="_blank"><img src="https://trendshift.io/api/badge/repositories/18533" alt="ryoppippi%2Fccusage | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

<div align="center">
    <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/screenshot.png">
</div>

> Analyze coding (agent) CLI token usage and costs from local data.

## Supported Sources

ccusage reads local usage data from coding agent CLIs and turns it into daily, weekly, monthly, and session reports.

| Source             | Focused command example  |
| ------------------ | ------------------------ |
| Claude Code        | `ccusage claude daily`   |
| Codex              | `ccusage codex daily`    |
| OpenCode           | `ccusage opencode daily` |
| Amp                | `ccusage amp daily`      |
| Droid              | `ccusage droid daily`    |
| Codebuff           | `ccusage codebuff daily` |
| Hermes Agent       | `ccusage hermes daily`   |
| pi-agent           | `ccusage pi daily`       |
| Goose              | `ccusage goose daily`    |
| OpenClaw           | `ccusage openclaw daily` |
| Kilo               | `ccusage kilo daily`     |
| Kimi               | `ccusage kimi daily`     |
| Qwen               | `ccusage qwen daily`     |
| GitHub Copilot CLI | `ccusage copilot daily`  |
| Gemini CLI         | `ccusage gemini daily`   |

Use `ccusage daily`, `ccusage weekly`, `ccusage monthly`, or `ccusage session` to include every detected source in one report.

## Installation

### Quick Start (Recommended)

You can run ccusage directly without a global installation:

```bash
# Recommended
bunx ccusage

# Nix
nix run github:ryoppippi/ccusage -- daily

# Alternative package runners
pnpm dlx ccusage
pnpx ccusage
npx ccusage@latest

# PR preview builds
bunx -p https://pkg.pr.new/ryoppippi/ccusage@<pr-number> ccusage --offline
```

> [bunx](https://bun.com/docs/pm/bunx) caches the downloaded package, so repeated runs are faster after the first launch.

## Usage

```bash
# Basic usage
bunx ccusage          # Show all detected sources by day (default)
bunx ccusage daily    # All detected sources by day
bunx ccusage weekly   # All detected sources by week
bunx ccusage monthly  # All detected sources by month
bunx ccusage session  # All detected sources by session
bunx ccusage blocks   # Claude Code 5-hour billing windows
bunx ccusage statusline  # Claude Code status line for hooks (Beta)

# Source-focused reports and options
bunx ccusage claude daily --mode display
bunx ccusage codex daily --speed fast
bunx ccusage opencode weekly
bunx ccusage amp session
bunx ccusage droid daily
bunx ccusage codebuff daily
bunx ccusage hermes daily
bunx ccusage goose daily
bunx ccusage openclaw daily
bunx ccusage kilo daily
bunx ccusage kimi daily
bunx ccusage qwen daily
bunx ccusage copilot daily
bunx ccusage gemini daily
bunx ccusage pi daily --pi-path /path/to/sessions
bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions

# Explicit unified report
bunx ccusage daily --all

# Filters and options
bunx ccusage daily --since 2026-04-25 --until 2026-05-16
bunx ccusage daily --json  # JSON output
bunx ccusage daily --timezone UTC  # Use UTC timezone

# Project analysis
bunx ccusage claude daily --instances  # Group Claude Code by project/instance
bunx ccusage claude daily --project myproject  # Filter to specific Claude project
bunx ccusage claude daily --instances --project myproject --json  # Combined usage

# Compact mode for screenshots/sharing
bunx ccusage --compact  # Force compact table mode
bunx ccusage monthly --compact  # Compact monthly report
```

## Features

- 📊 **Daily Report**: View token usage and costs aggregated by date
- 📅 **Monthly Report**: View token usage and costs aggregated by month
- 💬 **Session Report**: View usage grouped by conversation sessions
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, and Gemini CLI usage from one CLI
- ⏰ **5-Hour Blocks Report**: Track usage within Claude's billing windows with active block monitoring
- 🚀 **Statusline Integration**: Compact usage display for Claude Code status bar hooks (Beta)
- 🤖 **Model Tracking**: See which models are used across supported sources
- 📊 **Model Breakdown**: View per-model cost breakdown with `--breakdown` flag
- 📅 **Date Filtering**: Filter reports by date range using `--since` and `--until`
- 📁 **Custom Paths**: Support for custom local data directory locations
- 🎨 **Beautiful Output**: Colorful table-formatted display with automatic responsive layout
- 📱 **Smart Tables**: Automatic compact mode for narrow terminals (< 100 characters) with essential columns
- 📸 **Compact Mode**: Use `--compact` flag to force compact table layout, perfect for screenshots and sharing
- 📋 **Enhanced Model Display**: Model names shown as bulleted lists for better readability
- 📄 **JSON Output**: Export data in structured JSON format with `--json`
- 💰 **Cost Tracking**: Shows costs in USD for each day/month/session
- 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
- 🌐 **Offline Mode**: Use pre-cached pricing data without network connectivity with `--offline`
- 🏗️ **Claude Instance Support**: Group Claude Code usage by project with `--instances` and filter by specific projects
- 🌍 **Timezone Support**: Configure timezone for date grouping with `--timezone` option
- ⚙️ **Configuration Files**: Set defaults with JSON configuration files, complete with IDE autocomplete and validation

## Documentation

Full documentation is available at **[ccusage.com](https://ccusage.com/)**

## Development

<details>
<summary>Nix-based contributor setup</summary>

Use the Nix flake development environment. Install [Nix](https://nixos.org/) with the `nix-command` and `flakes` experimental features enabled, then use [nix-direnv](https://github.com/nix-community/nix-direnv) so the repository dev shell loads automatically when you enter the directory:

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

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

The dev shell provides the pinned `pnpm`, Rust toolchain, GitHub CLI, and project utilities from `flake.nix`. It also installs package dependencies from `pnpm-lock.yaml` when needed.

If you do not use direnv, enter the shell manually:

```sh
nix develop
```

Run the usual checks from inside the Nix environment:

```sh
pnpm run format
pnpm typecheck
pnpm run test
```

### Nix Package

The flake exposes `ccusage` as the default package and app:

```sh
nix run github:ryoppippi/ccusage
nix run github:ryoppippi/ccusage -- codex daily --offline
nix build github:ryoppippi/ccusage
```

Nix builds embed the LiteLLM pricing file from the locked `litellm` flake input, so sandboxed builds do not fetch pricing at build time. To update the locked pricing snapshot and refresh the non-Nix Cargo fallback JSON:

```bash
nix flake update litellm
nix run .#update-pricing-fallback
nix flake check
```

The scheduled `update pricing` workflow runs the same commands and opens a PR when the locked input changes.

</details>

## Sponsors

### Featured Sponsor

Check out [ccusage: The Claude Code cost scorecard that went viral](https://www.youtube.com/watch?v=Ak6qpQ5qdgk)

<p align="center">
    <a href="https://www.youtube.com/watch?v=Ak6qpQ5qdgk">
        <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/ccusage_thumbnail.png" alt="ccusage: The Claude Code cost scorecard that went viral" width="600">
    </a>
</p>

<p align="center">
    <a href="https://github.com/sponsors/ryoppippi">
        <img src="https://cdn.jsdelivr.net/gh/ryoppippi/sponsors@main/sponsors.svg">
    </a>
</p>

## Star History

<a href="https://www.star-history.com/#ryoppippi/ccusage&Date">
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date&theme=dark" />
        <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
        <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
    </picture>
</a>

## License

[MIT](LICENSE) © [@ryoppippi](https://github.com/ryoppippi)