Overview

Relevant source files

• .gitignore
• .mcp.json
• CLAUDE.md
• README.md
• apps/ccusage/package.json
• docs/package.json
• package.json
• pnpm-lock.yaml
• pnpm-workspace.yaml

ccusage is a high-performance CLI tool designed to analyze token usage and costs from local coding agent data. It supports a wide variety of agents, including Claude Code, GitHub Copilot, and various open-source alternatives, providing detailed reports on spending, token consumption, and session activity README.md60-83

Purpose and Scope

The project aims to provide developers and teams with transparency into their AI spending by parsing local logs and applying an embedded pricing engine. It bridges the gap between raw local agent logs (often in JSONL or SQLite formats) and human-readable summaries or structured JSON for further automation README.md24-25 CLAUDE.md35-40

Key features include:

• Multi-Agent Support: Unified reporting for Claude Code, Codex, Copilot, Gemini, and 13+ other sources README.md64-81
• Flexible Reporting: Daily, weekly, monthly, and session-based aggregation README.md112-117
• Pricing Engine: Built-in cost calculation using embedded LiteLLM and models.dev data.
• Performance: A core engine written in Rust for near-instant analysis of large log files CLAUDE.md38-40

For a quick introduction to running the tool, see Getting Started.

System Architecture

The ccusage system is split into a high-performance Rust core and a Node.js distribution layer CLAUDE.md44-47

Code Entity Mapping

The following diagram illustrates how natural language concepts map to specific code entities within the repository.

Sources: apps/ccusage/package.json17-19 CLAUDE.md38-40 apps/ccusage/src/cli.js1-23 CLAUDE.md44-47

Component Interaction

ccusage functions as a "Rust engine in a Node.js shell." The Node.js wrapper handles platform-specific binary resolution, while the Rust binary performs the heavy lifting apps/ccusage/src/cli.js1-23

Sources: README.md86-104 CLAUDE.md38-40 apps/ccusage/package.json33-40 apps/ccusage/src/cli.js1-23

Monorepo Organization

The project uses a pnpm workspace to manage both the JavaScript distribution logic and the Rust implementation package.json5-9 pnpm-workspace.yaml1-4

Path	Description
apps/ccusage	The main Node.js entry point and npm package source apps/ccusage/package.json1-41
rust/crates/	The core Rust workspace, containing the CLI engine and terminal UI logic CLAUDE.md38-40
packages/	Platform-specific native binary wrappers (e.g., ccusage-linux-x64) package.json8 pnpm-lock.yaml79-89
docs/	VitePress-based documentation site docs/package.json1-22
nix/	Nix flake modules for reproducible builds and dev shells CLAUDE.md42-43

For a detailed breakdown of the directory structure and build process, see Monorepo Layout.

Key Architectural Decisions

1. Rust Core: To ensure performance when parsing gigabytes of logs and to provide a robust pricing engine, the logic is implemented in Rust CLAUDE.md38-40
2. Nix-First Development: The project uses Nix flakes to manage dependencies like cargo, pnpm, and rust-toolchain, ensuring consistency across development and CI CLAUDE.md42-43
3. Embedded Data: Pricing data from LiteLLM and models.dev is embedded into the binary at compile time, allowing ccusage to work offline CLAUDE.md10
4. Adapter Pattern: Each agent source (Claude, Copilot, etc.) is implemented as a modular adapter under rust/adapters/ and rust/crates/ccusage/src/adapter/ CLAUDE.md14 CLAUDE.md44-47
5. Task Automation: The project uses just as a single entry point for development tasks, delegating to pnpm or nix as needed CLAUDE.md51

---

Child Pages

• Getting Started: Installation via npx, bunx, and nix, plus common command examples.
• Monorepo Layout: Deep dive into the workspace structure and how the Node/Rust boundary is managed.

Sources: package.json1-16 CLAUDE.md1-61 apps/ccusage/package.json1-41 docs/package.json1-22 pnpm-workspace.yaml1-42