ccusage-viz

简体中文 · Usage guide · Design philosophy · Architecture

Alpha · 0.1.0 — interfaces may change before 1.0. See the roadmap for planned work.

ccusage-viz is an independent, unofficial terminal visualizer for ccusage token data. It turns ccusage command output into interactive terminal charts without creating a second usage database. ccusage is required for real data and is not bundled with this project.

This project is not affiliated with or endorsed by the ccusage project or its maintainers.

Dashboard presets

dashboard composes independently configured charts in one terminal. Start with the default overview:

ccuv dashboard wide

wide (default)

A balanced 2×2 overview of Timeline, Stack, Ranking, and Monitor panes.

narrow

A compact, vertically focused layout for a narrower terminal.

all

A broad gallery that keeps several representative pane forms visible at once.

spotlight-wide

Timeline receives the leading full-width row; the remaining panes follow below.

spotlight-wide2

Timeline and Stack receive consecutive full-width rows before the smaller panes.

When to use a standalone chart

Choose a standalone view when you need to focus on one question rather than an overview composed from multiple panes.

Timeline

Use Timeline for daily token trends, grouped by model, agent, or project:

ccuv timeline

The 14-day view makes recent daily movement easy to compare.

The 13-month view makes longer-term changes visible at a coarser scale.

Calendar

Use Calendar to scan a longer period for active days, streaks, and concentrated usage:

ccuv calendar

Stack

Use Stack to compare input, output, and cache-token composition over time:

ccuv stack --cache split

This view emphasizes the overall composition of token types.

This variation separates cache reads from cache creation.

Ranking

Use Ranking to find the projects, models, or agents with the most tokens in a range:

ccuv ranking --by project

Monitor

Use Monitor for process-local throughput observed from repeated cumulative snapshots—not reconstructed hourly history:

ccuv monitor

An observed throughput window starts after a sampling baseline is established.

The grouped view ranks the selected dimension within the observed window.

The list view provides process and item detail alongside the observation.

For commands, filters, controls, styles, and data semantics, see the usage guide. The architecture overview is intended for maintainers.

Install, update, and remove

Requires Python 3.11–3.13. ccuv is the short alias for ccusage-viz; both installed commands behave the same way.

From uv

Install the isolated command-line tool:

uv tool install ccusage-viz
ccuv --version

Update or remove it:

uv tool upgrade ccusage-viz
uv tool uninstall ccusage-viz

From pip

Use an activated virtual environment, then install or update the package:

python -m pip install --upgrade ccusage-viz
ccuv --version

Remove it from that environment:

python -m pip uninstall ccusage-viz

From source

Clone the repository and install an editable tool:

git clone https://github.com/Cookie-HOO/ccusage-viz.git
cd ccusage-viz
uv sync --all-groups
uv tool install -e .
ccuv --help

After pulling newer source, refresh or remove the editable tool:

uv tool install --reinstall -e .
uv tool uninstall ccusage-viz

Missing ccusage?

Real-data commands need ccusage on PATH (or an explicit --ccusage-bin). If the default command is missing in an interactive terminal, ccuv offers:

npm install -g ccusage

An empty Enter or y/Y confirms that installation. Any other input, Ctrl-C, or EOF cancels it. Demo mode, redirected/noninteractive runs, and custom --ccusage-bin runs never prompt or install automatically. Install ccusage manually when npm is unavailable.

Further reading

ccusage-viz is token-only and stateless: it does not read raw Agent logs, store a usage database, or calculate cost, quota, QPM, or rate-limit metrics. These documents answer the deeper questions:

Report reproducible problems with the bug report form, or propose improvements through the feature request form.

Licensed under the GNU General Public License v3.0 only.