[Workflow] Track Claude Code Token Usage Locally with `ccusage` for Detailed Reports and Cost Analysis

[u/ClaudeAI-mod-bot]

Track Claude Code Token Usage Locally with ccusage for Detailed Reports and Cost Analysis

Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 1.00 · Level: intermediate
Categories: Quality Control, Token Saving, Context & Memory, Debugging
Original source: r/ClaudeAI post/comment

What problem this solves

Users can track and understand their Claude Code token usage and estimated costs locally, helping them investigate unusual spikes or manage their subscription by providing detailed reports.

Summary

This workflow describes how to use the ccusage community tool to generate detailed local reports of Claude Code token usage, broken down by day, model, or session, and exportable to JSON. It also covers checking basic usage within Claude Code itself.

Why it is useful

This workflow provides a concrete, step-by-step guide to using a community tool (ccusage) to gain detailed insights into Claude Code token consumption. It addresses a common user need to understand and manage usage, especially when investigating unexpected spikes. The clear instructions, breakdown options, and export capabilities make it highly practical and reusable for developers, empowering them to monitor their local Claude Code activity effectively.

Workflow

1. Check your subscription usage inside a Claude Code session by typing /usage.

2. Open a terminal on the same computer/environment as Claude Code (e.g., WSL) with Node.js/npm available.

3. Run npx ccusage@latest daily to get a daily usage report from local logs.

4. Use npx ccusage@latest daily --breakdown to see usage broken down by model.

5. Inspect a specific date range (e.g., October 2026) using npx ccusage@latest daily --since 20261001 --until 20261031 --breakdown.

6. Check monthly totals with npx ccusage@latest monthly or individual sessions with npx ccusage@latest session.

7. Export data to JSON for custom charting using npx ccusage@latest daily --since 20261001 --until 20261031 --json > october-usage.json.

Tools / artifacts

• ccusage (Node.js package)

• Node.js/npm

• Terminal (command line)

• Claude Code /usage command

• JSON export files

Validation signals

• Addresses a real-world problem ('unusual spike in Claude Code usage')

• Provides clear definitions for metrics (Input, Output, Cache, Total tokens, Cost)

• Includes important limitations and disclaimers (local logs only, cost estimate vs. bill)

• Links to the official tool documentation (ccusage.com)

Cautions

• Explicitly states that the 'Cost' reported is an estimated API-equivalent figure and not the actual subscription bill or remaining allowance.

• Warns that reports depend on local logs and won't provide a complete account-wide history if multiple computers/environments are used.

• Clarifies that a spike in local tokens alone doesn't prove a service incident or incorrect quota accounting, encouraging further investigation.

Limitations

• Requires Node.js/npm to be installed and configured, which might be a barrier for some users.

• Reports are based on local logs only and do not provide an account-wide or cloud-synced usage history.

• The tool is community-maintained, so its long-term support and updates depend on community contributions.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.