ccusage is a command-line interface (CLI) tool designed for comprehensive analysis of token usage and associated costs for Claude Code, specifically by processing data from local JSONL files. It aims to provide fast, informative, and visually appealing reports on daily, monthly, and session-based expenditures.

The core methodology of ccusage revolves around the ingestion and structured aggregation of local usage logs. The tool reads data from user-specified or default local JSONL files, which contain records of interactions with various AI models. Upon ingestion, ccusage performs several key analytical operations:

1. Time-Based Aggregation: It aggregates token usage and cost data across different temporal granularities. This includes daily reports (e.g., npx ccusage daily), monthly reports (npx ccusage monthly), and specialized 5-hour billing window reports (npx ccusage blocks), aligning with Claude's specific billing cycles.
2. Session-Based Analysis: The tool can group usage by individual conversation sessions (npx ccusage session), allowing users to track the resource consumption of specific interactions.
3. Model Tracking and Cost Breakdown: It identifies and reports on the specific Claude models utilized (e.g., Opus, Sonnet). A critical feature is the ability to generate a per-model cost breakdown (--breakdown), calculating costs in USD based on internal pricing data. Furthermore, ccusage explicitly differentiates and tracks "cache creation" and "cache read" tokens, providing a granular view of caching-related token consumption.
4. Project/Instance Management: For users managing multiple projects or instances, ccusage supports grouping usage data by project (--instances) and filtering reports to specific projects (--project <name>).
5. Filtering and Customization: Users can filter reports by date range using --since and --until flags, specify timezone (--timezone), and customize date/time formatting with locales (--locale).
6. Output Formats: Beyond colorful table-formatted displays, ccusage offers a JSON output option (--json) for programmatic integration and structured data export. It also provides compact modes (--compact) suitable for screenshots or terminal status lines (ccusage statusline).

The ccusage ecosystem extends its analytical capabilities through a family of companion tools, each tailored for different AI model providers: @ccusage/codex for OpenAI Codex (supporting GPT-5 and 1M token contexts), @ccusage/opencode for OpenCode, @ccusage/pi for pi-agent, and @ccusage/amp for Amp CLI (including credit tracking). A notable component is @ccusage/mcp (Model Context Protocol server), which enables real-time usage tracking by exposing ccusage data to compatible applications like Claude Desktop.

Technically, ccusage is designed for efficiency, boasting an "ultra-small bundle size." It is primarily run via npx, bunx, or pnpm dlx commands, often recommending the @latest tag for up-to-date features. For development, it leverages a Nix flake-based environment, ensuring consistent tooling and dependencies. The tool supports offline mode by utilizing pre-cached pricing data for Claude models.