This tools shows you how much you spend on tokens...

Key Concepts

• CC Usage: An open-source CLI (Command Line Interface) tool designed to analyze and track the usage and associated API costs of various AI coding agents.
• Agentic Terminals: Specialized terminal environments that utilize AI models to assist in software development tasks.
• Token Usage: The metric used to measure the amount of data processed by AI models (Input/Output tokens), which directly correlates to API costs.
• API Cost Analysis: The process of calculating the theoretical cost of AI usage based on pay-per-token pricing, regardless of whether the user has a flat-rate subscription.

---

1. Overview and Purpose

CC Usage (Coding Agent CLI Usage Analysis) is an open-source utility that provides developers with visibility into their AI coding agent consumption. The primary value proposition is cost transparency: by calculating the API-equivalent cost of usage, users can determine if their current monthly subscriptions are cost-effective compared to pay-as-you-go API pricing.

2. Installation Methods

The tool is designed for cross-platform compatibility and can be installed via several package managers:

• Bun: bunx cc-usage
• Nix: Available via Nix package management.
• PNPM: Supported for Node.js environments.
• Arch Linux: Available via the AUR (Arch User Repository) using helpers like yay (yay -S cc-usage).

3. Core Functionality and Command Framework

The tool operates directly within the terminal, providing granular data on token consumption and financial expenditure.

• General Overview: Running cc-usage displays a table containing the date, provider/tool name, input tokens, output tokens, total tokens, and the calculated cost in USD.
• Filtering Capabilities:
  • By Provider: cc-usage [provider] (e.g., cc-usage claude) isolates data for specific agents.
  • By Timeframe: Users can filter by daily, monthly, or specific date ranges using --since and --until flags (e.g., cc-usage --since 2026-05-14 --until 2026-05-26).
  • By Session: cc-usage [provider] session allows users to identify high-cost sessions, which is useful for auditing long-running development tasks.
  • Specific Metrics: For Claude Code, users can track usage against "blocks" (the 5-hour usage windows) using the blocks command.
• Data Export: The tool supports a --json flag, allowing the output to be piped into external scripts or automation pipelines for further data processing.

4. Important Considerations and Limitations

• Local Data Scope: The tool only tracks usage data stored locally on the machine where the command is executed. It does not aggregate data across multiple devices (e.g., a laptop, desktop, and cloud environment).
• Theoretical Costing: The financial figures represent the cost if the user were paying via API. This serves as a benchmark to evaluate the ROI of flat-rate subscriptions.

5. Synthesis and Takeaways

CC Usage is a highly effective diagnostic tool for developers who rely on AI-assisted coding. By providing a clear breakdown of token consumption and associated API costs, it empowers users to make data-driven decisions regarding their subscription models. The ability to filter by session and export data via JSON makes it particularly useful for power users looking to optimize their development workflows and manage their AI-related expenses effectively.