If you're using ccusage to watch Claude Code spend, cctally covers the same ground and adds the parts you reach for next: a live web dashboard, a forecast that tells you whether you're going to cap this week, threshold alerts when you cross a percent, and a persistent week-over-week trend of cost per percent of quota. All local, no account, no telemetry.

Installation

Requirements: Python 3.11+, macOS or Linux, Claude Code installed and run at least once.

Homebrew (macOS / Linux)

brew install omrikais/cctally/cctally
cctally setup

npm

npm install -g cctally
cctally setup

Needs Python 3. If cctally setup fails with "python3 not found", install it with brew install python (macOS) and try again.

From source

git clone https://github.com/omrikais/cctally
cd cctally
./bin/cctally setup

cctally setup (any channel) symlinks the binaries into ~/.local/bin/, adds three additive hooks to ~/.claude/settings.json (never overwrites existing entries), and bootstraps the local SQLite cache. If ~/.local/bin/ isn't on your PATH, the script prints the line to add.

cctally setup --status     # verify hooks + symlinks
cctally daily              # cost-by-day, your first table
cctally dashboard          # opens http://127.0.0.1:8789

For status-line integration, alerts, and configuration, see docs/installation.md and docs/configuration.md.

What it looks like

Dashboard

CLI tables

Live terminal

What cctally adds

cctally started as a local-first replacement for ccusage, and it stays compatible at the level of common CLI flows (daily, monthly, weekly, session, blocks). Paste from ccusage verbatim: cctally claude <cmd> is a drop-in for ccusage claude <cmd> (and cctally codex <cmd> for ccusage codex <cmd>), with the flat forms (cctally daily, cctally codex-daily, …) kept as aliases. Beyond that, it adds:

• Live web dashboard. Nine-panel SSE-driven view at localhost:8789 (current week, forecast, trend, sessions, weekly, monthly, blocks, daily, recent alerts), with per-panel modals, a mobile layout, threshold alerts, and a settings drawer.
• TUI live mode. The same data inside your terminal (cctally tui; requires the optional rich package).
• $-per-1% weekly trend. The report table reframes weekly cost as cost-per-percent-of-quota, so spending efficiency is visible week over week.
• Forecast. Projects current-week percent and daily $/% budgets against the 100% and 90% ceilings (cctally forecast).
• Threshold alerts. Configurable percent crossings with native macOS popups (cctally alerts).
• 5-hour block analytics. Per-block usage with model and project breakdowns (cctally five-hour-blocks --breakdown=model).
• Time-window diff. Compare two windows with model and project decomposition (cctally diff).
• Project rollup. Usage by Git project (cctally project).
• Codex parity. cctally codex daily / monthly / session are drop-ins for ccusage codex daily / monthly / session; the flat codex-* forms (drop-ins for the standalone ccusage-codex binary) remain as aliases, plus an added cctally codex weekly / cctally codex-weekly rollup (upstream has no codex weekly).
• Persistent SQLite. Week-over-week comparisons survive across runs.

On speed. Pricing is embedded and computed at query time from a delta-tail SQLite cache (~/.local/share/cctally/cache.db), with no shell-outs. First-table latency on 30 days of session data: ~2.6s (cctally) vs ~31s (ccusage), about 12× faster. Measured by bench/cctally-vs-ccusage.sh on macOS arm64, 2026-05-05; your numbers will vary.[^bench]

[^bench]: Methodology and reproduction: bench/README.md.

Documentation

• Installation: symlinks, status-line wiring, Python version.
• Configuration: config.json shape and week-start rules.
• Architecture: data flow, caches, week boundaries.
• Runtime data: what lives in ~/.local/share/cctally/.
• Command reference: one page per subcommand.

License

Apache 2.0. See LICENSE.