README.md

Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.

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

Any panel expands into a focused view. The trend modal shows twelve weeks of cost per percent.	When the forecast projects a cap before the weekly reset, the modal goes amber.
The same dashboard on your phone.

CLI tables

Weekly cost as dollars per percent of quota, with the delta against the prior week.

Projected percent at the weekly reset, plus the daily budget to stay under the cap.

Each 5-hour window, broken down by model.

Live terminal

The same data in the terminal, refreshed live.

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

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.

Footnotes

1. Methodology and reproduction: bench/README.md. ↩