This document provides a comprehensive overview of the ccusage monorepo, its architecture, and the family of CLI tools it contains for analyzing AI coding assistant token usage and costs.
Purpose: The ccusage monorepo is a collection of command-line tools that parse local JSONL log files from various AI coding assistants (Claude Code, OpenAI Codex, OpenCode, Pi-agent, Amp) and generate detailed usage reports with cost analysis. All tools share common infrastructure for pricing calculations, data aggregation, and terminal output rendering.
Scope: This page covers the overall monorepo structure, the relationship between applications and shared packages, core data processing workflows, and the infrastructure used for development and deployment. For specific tool usage details, see Getting Started. For individual application documentation, see Applications and Packages. For architectural deep-dives, see Architecture.
ccusage is a family of six applications built on shared infrastructure that analyze token usage and compute costs from AI coding assistant session logs:
| Application | Package Name | Purpose | Data Source |
|---|---|---|---|
| ccusage | ccusage | Claude Code usage analysis | ~/.claude/projects/ or ~/.config/claude/projects/ |
| codex | @ccusage/codex | OpenAI Codex usage analysis | ~/.codex/ (via CODEX_HOME) |
| opencode | @ccusage/opencode | OpenCode session analysis | sessions/ (via OPENCODE_DATA_DIR) |
| pi | @ccusage/pi | Pi-agent usage tracking | ~/.pi/agent/ (via PI_AGENT_DIR) |
| amp | @ccusage/amp | Amp CLI session analysis | threads/ (via AMP_DATA_DIR) |
| mcp | @ccusage/mcp | Model Context Protocol server | Exposes ccusage data via MCP |
All applications provide similar reporting capabilities: daily, monthly, and session-based usage reports with cost calculations. The ccusage application additionally supports weekly reports, 5-hour billing blocks analysis, and statusline integration for Claude Code.
Sources: README.md1-47 package.json1-9
The ccusage repository is structured as a pnpm workspace monorepo with the following layout:
Workspace Configuration: The monorepo uses pnpm workspaces defined in package.json6-9 with applications under apps/* and documentation under docs. Shared utilities are located in packages/* but are not explicitly listed in workspaces as pnpm automatically discovers packages referenced by workspace apps.
Package Manager: The repository enforces pnpm (pnpm@10.30.1) via package.json10 and includes a preinstall hook at package.json32 that rejects other package managers.
Dependency Management: All applications are bundled CLIs that list runtime dependencies as devDependencies rather than dependencies, as noted in CLAUDE.md17-19 This ensures the bundler controls the runtime payload.
Sources: package.json1-63 CLAUDE.md5-19
Each application under apps/* follows a consistent structure:
gunshi for command routing (see CLAUDE.md92)daily, monthly, session) with application-specific additions@ccusage/terminal package or JSON via --json flagtsdown into standalone executablesThe primary application ccusage provides the most comprehensive feature set including weekly reports, 5-hour blocks analysis, and statusline integration for Claude Code's status bar.
Sources: CLAUDE.md86-104 README.md22-46
@ccusage/internal Package:
LiteLLMPricingFetcher class fetches model pricing from LiteLLM API with offline caching support (see CLAUDE.md119)consola with configurable log levels via LOG_LEVEL environment variable CLAUDE.md68-70prefetchClaudePricing macro embeds pricing snapshots at build time for offline mode@ccusage/terminal Package:
ResponsiveTable class adapts layout based on terminal width README.md119--compact flag README.md119-120Sources: README.md107-131 CLAUDE.md68-70 CLAUDE.md119
Data Discovery: Applications search for data directories using environment variables first, then fall back to default locations. For Claude Code, both ~/.config/claude/projects/ (new) and ~/.claude/projects/ (old) are checked automatically CLAUDE.md73-83
Parsing and Validation: JSONL files are read line-by-line, with each line parsed as JSON and validated against schemas. Invalid lines are silently skipped CLAUDE.md207 The codebase uses the @praha/byethrow Result type for functional error handling CLAUDE.md213-220
Aggregation: Raw usage entries are grouped by different time windows or session identifiers depending on the selected report type. Each aggregator function sums token counts and tracks unique models used.
Cost Calculation: The LiteLLMPricingFetcher retrieves model pricing from the LiteLLM API CLAUDE.md289-294 For models with tiered pricing (1M+ context), costs scale above 200k token thresholds. Three cost modes are supported: auto (use pre-calculated when available), calculate (always compute from tokens), and display (use pre-calculated only) CLAUDE.md60-64
Rendering: Output adapts based on terminal width and user flags. The ResponsiveTable class automatically switches to compact mode for narrow terminals README.md119 JSON output is available via --json flag for programmatic consumption README.md122
Sources: CLAUDE.md73-83 CLAUDE.md86-120 CLAUDE.md207 CLAUDE.md213-220 CLAUDE.md289-294 CLAUDE.md60-64 README.md119-122
Command Entry: The CLI is built with the gunshi framework, with the main entry point at index.ts CLAUDE.md94 Commands can be invoked via various package runners:
npx ccusage@latest (recommended)bunx ccusagepnpm dlx ccusagedeno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latestExecution Options: For Claude Code users, the tool can leverage the bundled Bun runtime via BUN_BE_BUN=1 claude x ccusage README.md54-67
Command Organization: Each report type is implemented as a separate command file under commands/ directory. The main command defaults to the daily report CLAUDE.md94
Option Handling: All commands accept common filtering options (--since, --until, --project, --instances), output options (--json, --breakdown, --compact), and configuration options (--timezone, --locale, --offline, --mode) README.md90-105
Sources: README.md54-105 CLAUDE.md94
The @ccusage/mcp package provides a Model Context Protocol server that exposes ccusage functionality as MCP tools:
Server Invocation: The MCP server can be started directly via pnpm dlx @ccusage/mcp@latest with options for transport type (--type stdio or --type http) and port (--port 8080 for HTTP) CLAUDE.md56-58
Integration Methods:
Tool Implementation: The four MCP tools (daily, monthly, session, blocks) reuse the core ccusage data loading, aggregation, and cost calculation logic, ensuring consistency with CLI output README.md126
Configuration: Claude Desktop users configure the server in mcpServers configuration, while Claude Code users can add via claude mcp add command.
Sources: CLAUDE.md56-58 README.md44-46 README.md126
Development Setup: The repository uses a Nix flake at flake.nix to provide a reproducible development environment with all required tools. The .envrc file enables automatic environment activation via direnv README.md139-155
Build Process: Applications are bundled using tsdown, generating standalone CLI executables in dist/ directories. The build also generates JSON schemas for configuration validation and prepares packages for publishing via clean-pkg-json CLAUDE.md30-33
Code Quality: Multiple quality checks run in parallel via pnpm scripts:
@ryoppippi/eslint-config using tab indentation and double quotes CLAUDE.md204-206tsgo --noEmit package.json43Testing Guidelines: This project uses in-source testing with if (import.meta.vitest != null) blocks. Tests are written directly in source files, and Vitest globals (describe, it, expect) are enabled without imports CLAUDE.md275-281 Test data is created using fs-fixture with createFixture() for simulating Claude data directories CLAUDE.md282
Sources: README.md139-155 CLAUDE.md23-43 CLAUDE.md204-287 package.json25-43
Release Process:
pnpm run prerelease to prepare packages package.json39pnpm bumpp -r for version bumping package.json40changelogithub generates release notes from commits package.json52Documentation System:
docs/ built with VitePress docs/package.json11typedoc docs/package.json14wrangler docs/package.json12public/config-schema.json during build docs/package.json11Commit Conventions: The project follows Conventional Commits with scope-based prefixes. App changes use app directory names (feat(ccusage):, fix(mcp):), package changes use package names (feat(terminal):), and root changes omit scope or use root CLAUDE.md136-200
Sources: package.json39-52 docs/package.json1-38 CLAUDE.md136-200
| Category | Technology | Purpose |
|---|---|---|
| CLI Framework | gunshi | Command routing and argument parsing |
| Bundler | tsdown | TypeScript bundling for CLI distribution |
| Testing | vitest | In-source testing with ESM support |
| Terminal Output | cli-table3 | Table rendering for reports |
| Error Handling | @praha/byethrow | Result type for functional error handling |
| Pricing Data | LiteLLM API | Model pricing database integration |
| Package Manager | pnpm | Workspace and dependency management |
| Environment | Nix | Reproducible development shell |
| Documentation | VitePress + TypeDoc | Static site generation + API docs |
| Linting | ESLint + oxfmt | Code quality and formatting |
| CI/CD | GitHub Actions | Automated testing and publishing |
Sources: package.json46-57 docs/package.json20-37 CLAUDE.md118-133
Applications support configuration through multiple layers with the following precedence: CLI flags > environment variables > config files > defaults CLAUDE.md5
Environment Variables:
CLAUDE_CONFIG_DIR: Custom Claude data directory path(s), comma-separated for multiple CLAUDE.md77-79CODEX_HOME: OpenAI Codex data directory locationOPENCODE_DATA_DIR: OpenCode sessions directoryPI_AGENT_DIR: Pi-agent data directoryAMP_DATA_DIR: Amp threads directoryLOG_LEVEL: Logging verbosity (0=silent, 1=warn, 2=log, 3=info, 4=debug, 5=trace) CLAUDE.md68-70Configuration Files: JSON configuration files provide IDE autocomplete and validation through generated schemas. Files can set defaults for timezone, locale, offline mode, cost calculation mode, and other options README.md130
Directory Detection: Applications automatically discover data directories using platform-specific defaults with fallback logic. For Claude Code, both ~/.config/claude/projects/ and ~/.claude/projects/ are checked to handle the breaking change in Claude Code's directory structure CLAUDE.md73-83
Sources: CLAUDE.md68-83 README.md130
This overview provides the foundation for understanding the ccusage monorepo. For detailed information about specific components, refer to the subsections: Monorepo Structure, Applications and Packages, and subsequent sections of this wiki.
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.