Check website

How to use ccusage: commands, filters and a dashboard option

A short walkthrough of the ccusage reports and flags, and when UsageAtlas is the easier way to keep limits in view.

By ClaudeGPT Si Newsroom, Editorial team··3 min read

Here is how to use ccusage in one line: run npx ccusage@latest in a terminal. It reads the usage files your coding agents keep on disk and prints a table of tokens and estimated cost per day. Add a report name such as weekly or session, or a tool name such as claude or codex, to change the view, and switch to UsageAtlas when you want the same data on a desktop dashboard with limits and alerts.

Step 1: run it without installing

ccusage is free and MIT licensed, and it does not need a global install. Pick the runner you already have:

  • npx ccusage@latest with Node.js
  • bunx ccusage with Bun
  • pnpm dlx ccusage with pnpm

The first run prints a daily report for every coding tool it detects. Its supported list includes Claude Code, Codex, OpenCode, Amp, Droid, Gemini CLI, GitHub Copilot CLI and several more.

Step 2: choose a report

Command What you get
ccusage daily Tokens and cost per day
ccusage weekly Totals per week
ccusage monthly Totals per month
ccusage session Usage grouped by conversation
ccusage blocks Claude Code's five-hour windows

Put a tool name in front of the report to narrow it, for example ccusage claude daily or ccusage codex session.

Step 3: filter and export

The options most people need:

  • --since 2026-10-01 --until 2026-10-26 limits the date range.
  • --last 1 jumps to today, this week or this month, depending on the report.
  • --breakdown splits cost by model.
  • --json gives you machine-readable output for a script or a spreadsheet.
  • --timezone UTC groups days in a fixed time zone.
  • --offline uses cached pricing when you have no network.

For Claude Code, --instances groups usage by project, and ccusage statusline adds a compact usage line to the Claude Code status bar (marked beta). If you run the same flags every time, ccusage also reads defaults from a JSON configuration file, so you can skip retyping them.

Step 4: read the numbers carefully

ccusage turns token counts into dollars using model prices, so the figure is an estimate. Anthropic says the same about the cost shown by Claude Code's own /usage command. If you pay per token, your provider's billing page is the final word. If you are on a subscription plan, remaining capacity in each window usually matters more than a dollar total.

When a dashboard works better

ccusage answers a question when you ask it. Some questions are easier to answer if the data is always on screen:

  • How much of my weekly Claude Code window is left, and when does it reset?
  • Am I about to hit my Codex limit in the middle of a task?
  • What did I use in Cursor this week, next to Claude Code?

UsageAtlas is a free, open-source desktop app built for those. It shows tokens, requests, models, cost estimates, usage windows and reset times across 14 coding tools, including Cursor, which ccusage does not list. It keeps a history with a per-tool filter and can send a desktop alert once per reset cycle when a window crosses your threshold.

Local tracking needs no account, prompts and responses are not read, and it runs on Windows, macOS and Linux.

Keep ccusage for scripts

If you need JSON in a pipeline or a quick check over SSH, ccusage is still the right tool, and nothing stops you running it alongside UsageAtlas. For a daily view of your limits and history, though, the free UsageAtlas desktop app saves you from typing the command again.