Code CLI Usage Skill

Query and analyze token consumption and costs from local Claude Code and Codex interactions. Uses the ccusage CLI tool to parse local JSONL session files.

Quick Reference

Prerequisites

• •Node.js (v18+) must be installed
• •npx must be available (comes with npm)
• •No additional installation needed; the script runs npx ccusage@latest directly

Main Wrapper Script

./scripts/codecliusage.sh [--tool claude|codex] [command] [options]

Wrapper around ccusage / @ccusage/codex that provides a unified interface for querying Claude Code and Codex token usage.

Tool Selection:

• •--tool claude - Query Claude Code usage (default)
• •--tool codex - Query OpenAI Codex usage

Commands:

• •daily - Daily token usage and costs (default if omitted)
• •monthly - Monthly aggregated report
• •session - Usage grouped by conversation session
• •blocks - 5-hour billing window tracking
• •statusline - Compact status line for hooks (Beta)

Common Options:

• •--since YYYYMMDD - Start date filter
• •--until YYYYMMDD - End date filter
• •--json - JSON output format
• •--breakdown - Per-model cost breakdown
• •--compact - Force compact table layout
• •--instances - Group by project/instance
• •--project <name> - Filter to specific project
• •--timezone <tz> - Timezone for date grouping (e.g., UTC)
• •--locale <locale> - Date/time formatting locale (e.g., ja-JP)
• •--offline - Use pre-cached pricing data (no network)

Common Workflows

Check Today's Usage

# Quick daily overview
./scripts/codecliusage.sh

# With per-model cost breakdown
./scripts/codecliusage.sh daily --breakdown

Review a Specific Date Range

./scripts/codecliusage.sh daily --since 20250601 --until 20250630

Monthly Cost Summary

./scripts/codecliusage.sh monthly

# With compact table for sharing
./scripts/codecliusage.sh monthly --compact

Per-Project Analysis

# See all projects
./scripts/codecliusage.sh daily --instances

# Focus on a specific project
./scripts/codecliusage.sh daily --instances --project myproject

Export Data as JSON

# Pipe to jq for further processing
./scripts/codecliusage.sh daily --json | jq '.[] | {date, totalCost}'

Check Codex Usage

./scripts/codecliusage.sh --tool codex daily
./scripts/codecliusage.sh --tool codex monthly --breakdown

Troubleshooting

npx Not Found

Ensure Node.js and npm are installed:

node --version
npm --version

No Data Returned

• •Claude Code session logs are stored in ~/.claude/projects/. Ensure this directory exists and contains .jsonl files.
• •Check that the date range (--since, --until) covers periods with actual usage.

Slow Startup

The first run may be slow as npx downloads ccusage@latest. Subsequent runs use the cached version. Use --offline to skip pricing data fetch if you only need Claude model costs.

Tips

1. •Start with daily - It's the default and gives you a quick overview of recent usage
2. •Use --breakdown - See exactly which models are consuming tokens
3. •Use --instances - Identify which projects are the most expensive
4. •Use --json + jq - For scripting and custom analysis
5. •Use --compact - Better for narrow terminals or screenshots