Skip to main content

​
ccusage Family

The ccusage family is a suite of CLI tools designed to track token usage and costs across various AI coding assistants. All tools share the same powerful reporting features and beautiful terminal output.

ccusage

Main CLI tool for analyzing Claude Code usage from local JSONL files

@ccusage/codex

OpenAI Codex usage analyzer with GPT-5 support

@ccusage/opencode

OpenCode usage analyzer for tracking sessions

@ccusage/pi

Pi-agent usage analyzer for alternative Claude agent

@ccusage/amp

Amp usage analyzer with credits tracking

@ccusage/mcp

MCP server for real-time integration with Claude Desktop

​
Common Features

All tools in the ccusage family share these powerful features:
  • Daily Reports - View token usage and costs aggregated by date
  • Monthly Reports - View usage grouped by month
  • Session Reports - Analyze individual conversation sessions
  • Model Tracking - See which AI models you’re using
  • Cost Calculation - Accurate USD cost estimates using LiteLLM pricing
  • Cache Token Support - Track cache creation and cache read tokens separately
  • JSON Output - Export data in structured JSON format with --json
  • Beautiful Tables - Colorful terminal output with automatic responsive layout
  • Compact Mode - Use --compact flag for narrow terminals
  • Offline Support - Use cached pricing data without network connectivity

​
Installation

All ccusage family tools can be run directly without installation using npx or bunx: 
npx ccusage@latest
We recommend always using @latest suffix to ensure you get the newest version with the latest features and bug fixes.

​
Shell Aliases

Since the scoped package names can be long, we recommend setting up shell aliases: 
# bash/zsh
alias ccusage-codex='bunx @ccusage/codex@latest'
alias ccusage-opencode='bunx @ccusage/opencode@latest'
alias ccusage-pi='bunx @ccusage/pi@latest'
alias ccusage-amp='bunx @ccusage/amp@latest'

# fish
alias ccusage-codex 'bunx @ccusage/codex@latest'
alias ccusage-opencode 'bunx @ccusage/opencode@latest'
alias ccusage-pi 'bunx @ccusage/pi@latest'
alias ccusage-amp 'bunx @ccusage/amp@latest'

​
Use Cases

Each tool is designed for specific AI coding assistants:
ToolUse CaseData Source
ccusageTrack Claude Code token usage and costs~/.claude/projects/ or ~/.config/claude/projects/
@ccusage/codexMonitor OpenAI Codex sessions with GPT-5 support~/.codex/sessions/
@ccusage/opencodeAnalyze OpenCode session usage and costs~/.local/share/opencode/
@ccusage/piTrack pi-agent sessions (alternative Claude agent)~/.pi/agent/sessions/
@ccusage/ampMonitor Amp CLI usage with credits tracking~/.local/share/amp/threads/
@ccusage/mcpReal-time integration with Claude Desktop via MCPAll supported tools

​
Learn More

Explore the individual tool pages for detailed usage instructions and examples:

Build docs developers (and LLMs) love

Get started for freeTalk to us