ccusage-viz

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

Alpha · 0.2.1 — 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 focuses exclusively on token consumption and metrics derived from token consumption, such as observed tokens per minute (TPM). It does not provide session analytics, request counts, elapsed-time metrics, costs, pricing, balances, quotas, allowances, or other non-token account analytics.

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. The default preset is wide-clock:

ccuv dashboard

Preset	Command	Layout	Preview
【Recommended—wide terminal】 wide-clock (default)	ccuv dashboard wide-clock	Best for an all-purpose overview with a live clock. 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.

Animation overlays

Add run-local context to a standalone animation or an explicit Dashboard Animation Pane: place static text, show a localized time state, or render output from a trusted local command.

ccuv animate rain --overlay-text "Focus time"
ccuv animate analog-clock --overlay-command "ccuv text time-state --run"
ccuv animate rain --overlay-command "date"

See the usage guide for Overlay options, refresh behavior, and Dashboard Animation Pane syntax.

Standalone views

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

Category	View	Command	Use it for	Preview
Trends timeline	Timeline — 14 days	ccuv timeline	Recent daily token trends grouped by model, agent, or project.
Trends timeline	Timeline — 13 months	ccuv timeline --period 13mo	Longer-term changes at a coarser scale.
Activity heatmap calendar	Calendar	ccuv calendar	Active days, streaks, and concentrated usage over a longer period.
Token composition stack	Stack — composition	ccuv stack	Overall input, output, and cache-token composition over time.
Token composition stack	Stack — cache split	ccuv stack --cache split	Cache reads versus cache creation over time.
Historical ranking ranking	Ranking	ccuv 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. Space pauses or resumes playback; m opens local style and theme controls.
Usage monitoring monitor	Monitor — throughput	ccuv monitor	Process-local throughput from repeated cumulative snapshots, not reconstructed hourly history. The observation begins after its sampling baseline; Timeline marks the invocation start while visible.
Usage monitoring monitor	Monitor — cumulative bars	ccuv 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.
Usage monitoring monitor	Monitor — grouped ranking	ccuv monitor --by project	The selected dimension ranked within its observed window.
Usage monitoring monitor	Monitor — list	ccuv monitor	Process and item detail alongside the observation.
Usage monitoring 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.

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 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.