ccusage-viz

简体中文 · Usage guide · Custom command protocol · Design philosophy · Architecture · Versioning

Alpha · 0.3.0 — interfaces may change before 1.0. See the roadmap for current direction.

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. It currently relies primarily on ccusage for real data; ccusage is required and is not bundled with this project.

Quick start

uv tool install ccusage-viz
ccuv dashboard

Supported agents

Agent coverage follows ccusage. Its current supported agents include Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode. See the ccusage support list for the authoritative and up-to-date list, plus setup and source-specific details.

Product scope

ccusage-viz visualizes built-in token consumption and metrics derived from it, such as observed tokens per minute (TPM). It does not provide built-in session analytics, request counts, elapsed-time metrics, costs, pricing, balances, quotas, allowances, or other non-token account analytics. A registered Dataset can separately add its own externally owned metrics—such as reading, CI, builds, spend, bytes, or local-service activity—without changing ccusage token collection.

Historical date boundaries use the local IANA timezone by default. Pass --timezone AREA/LOCATION to select another calendar context; copied commands retain the resolved timezone. ccuv sends that timezone explicitly to every custom Dataset request, while a Dataset may return a non-blocking warning if it cannot apply the requested timezone.

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

Dataset and custom command extensions

Datasets let ccuv visualize metrics owned by external sources without adding them to built-in ccusage token collection. A Dataset is an executable command: ccuv sends it one JSON request on stdin, reads one JSON response from stdout, and renders the declared Metrics in focused charts or Dashboard Panes.

Install an official Dataset

Official Dataset entries are collected in the signed Cookie-HOO/ccuv-dataset-catalog repository.

1. Run ccuv dataset.
2. Press + and choose Browse official datasets.
3. Select an entry, review its Metrics, environment requirements, version, and source, then confirm installation.

The official catalog verifies signed metadata. Installation still requires a compatible release archive for the current operating system and architecture.

Register a local command

Register an executable already available on your machine with its exact argv:

ccuv dataset add-local /absolute/path/to/my-dataset --profile personal
ccuv dataset list

Registration immediately runs the command's Probe. Use the Dataset ID returned by that Probe—not the executable filename—with --dataset. ccuv stores argv and starts the executable directly without a shell. Re-run add-local after changing its Probe metadata; a local registration with the same Dataset ID is replaced.

Install from a GitHub repository

You can also install a compatible Dataset from a specific GitHub repository. For example, use the WeRead Dataset:

1. Run ccuv dataset, press +, and choose Install from GitHub.

2. Enter:

   https://github.com/Cookie-HOO/ccuv-dataset-weread
   

3. Review the discovered release and confirm installation.

The repository must publish a compatible native archive, checksum, and Dataset manifest. Installing from an arbitrary GitHub repository does not make it an official Dataset; if the repository is also present in the official catalog, ccuv uses its verified official artifact path.

For installation, management, Dashboard selection, and troubleshooting, see the Dataset user guide. To implement and package a Dataset, start with the Dataset developer guide and custom command protocol.

Interactive Help

Dashboard provides contextual Help: press h to see the controls for the active surface, and press c in chart-browse mode to show or hide its footer. While editing Overlay text or a command, use Ctrl-H instead so the literal h remains available to the draft.

Dashboard presets

dashboard composes independently configured charts in one terminal. Without a positional preset, dashboard defaults to wide-clock:

ccuv dashboard

Preset	Command	Layout	Preview
single	ccuv dashboard single	A single live analog clock without a text overlay or Dashboard frame.	-
【Recommended—wide terminal】 wide-clock (default without a preset)	ccuv dashboard wide-clock	Best for an all-purpose overview with a compact live digital clock. Digital clock + balanced 2×2.
【Recommended—sidebar】 narrow-clock	ccuv dashboard narrow-clock	Best for a sidebar with a live clock. Clock + vertical 4×1.
wide	ccuv dashboard wide	Best for a balanced data-only overview. Balanced 2×2.
narrow	ccuv dashboard narrow	Best for a compact, narrow-terminal overview. Vertical focus.
all	ccuv dashboard all	Best for comparing many pane types at once. Broad gallery.
spotlight-wide	ccuv dashboard spotlight-wide	Best for prioritizing Timeline trends. Timeline-led.
spotlight-wide2	ccuv dashboard spotlight-wide2	Best for prioritizing Timeline and Stack together. Timeline + Stack-led.

Your Dashboard presets

In Dashboard browse mode, press Ctrl-S to save the current Dashboard under a name, or Ctrl-P to open the full-screen preset manager. The manager lists built-in and your saved presets; use arrows or j/k to select, Enter to load, s to save, and x to delete a selected user preset. Built-ins can be loaded but not deleted. Saving a user preset with a built-in name intentionally overrides it; deleting that user preset reveals the built-in again. Saving over an existing user preset asks whether to overwrite or cancel.

Preset names must match ^[a-z][a-z0-9-]*$. A saved name can be launched in a fresh terminal with ccuv dashboard <name>. A named launch is closed to configuration overrides: only --demo, --lang, --empty, and --ccusage-bin may accompany it. For example:

ccuv dashboard weekly-review
ccuv dashboard weekly-review --demo --lang zh-CN
ccuv dashboard weekly-review --empty
ccuv dashboard weekly-review --ccusage-bin /opt/bin/ccusage

With a named preset, --empty keeps its layout, weights, display settings, refresh/sampling cadence, timezone, demo and process settings, but replaces every pane with an empty pane in memory; it never changes the saved preset. The ordinary unnamed ccuv dashboard --empty flow remains available for composing a new temporary Dashboard. A demo-enabled preset stays demo-enabled when loaded; Dashboard currently has no runtime control for turning demo off.

Presets persist declarative Dashboard configuration, including installed Dataset references, local-command argv, and executable Overlay commands, but never query results, environments, credentials, or UI/runtime state. Presets are trusted user-local automation: load only presets you trust, because loading one can run the commands it contains. Presets live in ccuv's private state directory under dashboard-presets/presets.json (~/Library/Application Support/ccuv on macOS, %LOCALAPPDATA%/ccuv on Windows, or ${XDG_STATE_HOME:-~/.local/state}/ccuv on other systems). A missing installed Dataset leaves a preset loadable and its pane reports the unavailable source; only unreadable, malformed, or unsupported preset storage is shown as unavailable and protected from overwrites.

Focused chart views

ccuv chart KIND ... is a shortcut to a focused one-Pane Dashboard: it starts with the requested chart, hides the Dashboard header and global summary, and then uses the same Pane controls and lifecycle as every Dashboard. You can keep it focused, replace the Pane, or expand it into a multi-Pane Dashboard.

Category	View	Command	Use it for	Preview
Timeline timeline	Timeline — 14 days	ccuv chart timeline	Recent daily token trends grouped by model, agent, or project.
Timeline timeline	Timeline — 13 months	ccuv chart timeline --period 13mo	Longer-term changes at a coarser scale.
Calendar calendar	Calendar	ccuv chart calendar	Active days, streaks, and concentrated usage over a longer period.
Stack stack	Stack — composition	ccuv chart stack	Overall input, output, and cache-token composition over time.
Stack stack	Stack — cache split	ccuv chart stack --cache split	Cache reads versus cache creation over time.
Ranking ranking	Ranking	ccuv chart ranking --by project	Projects, models, or agents with the most tokens in a range.
Terminal animations animate	Animation gallery	ccuv animate --gallery	Provider-free presentation-only animations; optionally specify a style, for example ccuv animate digital-clock --gallery. m opens local style and theme controls.
Monitor monitor	Trend	ccuv chart monitor	Process-local throughput from repeated cumulative snapshots, not reconstructed hourly history. The observation begins after its sampling baseline; Timeline styles mark the invocation start while visible.
Monitor monitor	Cumulative bars	ccuv chart monitor --style cumulative-bars	Retained local-day token increments. Press w for Today/Yesterday and g for hourly/half-hour buckets; unobserved periods remain distinct from observed zero values.
Monitor monitor	Ranking	ccuv chart monitor --style ranking --by project	The selected dimension ranked within its observed window.
Monitor monitor	List	ccuv chart monitor --style list	Process and item detail alongside the observation.
Monitor monitor	Animation attachment	In Monitor ranking or list: press m, then s	Optional animation below the data. Disabled by default; s/S cycles eligible effects and ccuv-local none, while t/T changes only its theme. It waits for a comparable accepted interval and never causes another usage query.

A declared V2 Dataset can independently rank real models within each logical model:

ccuv chart ranking --dataset router --partition-by logical_model --group-by real_model

For commands, filters, controls, styles, and data semantics, see the usage guide. To install, register, or use external Metrics, read the Dataset user guide; Dataset authors should start with the developer 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 analyze Agent transcripts, store a usage database, or calculate cost, quota, QPM, or rate-limit metrics. For Codex project attribution only, it may read the matching local session's session_meta.cwd; it never stores or displays session-log content. 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.