https://github.com/omrikais/cctally
Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.
https://github.com/omrikais/cctally
anthropic ccusage ccusage-alternative claude claude-code claude-code-cost claude-code-dashboard claude-code-quota cli codex cost-tracking dashboard developer-tools homebrew npm-package productivity python quota-tracking tui usage-tracker
Last synced: 12 days ago
JSON representation
Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.
- Host: GitHub
- URL: https://github.com/omrikais/cctally
- Owner: omrikais
- License: apache-2.0
- Created: 2026-05-04T09:05:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-11T21:59:10.000Z (16 days ago)
- Last Synced: 2026-06-11T23:12:59.585Z (16 days ago)
- Topics: anthropic, ccusage, ccusage-alternative, claude, claude-code, claude-code-cost, claude-code-dashboard, claude-code-quota, cli, codex, cost-tracking, dashboard, developer-tools, homebrew, npm-package, productivity, python, quota-tracking, tui, usage-tracker
- Language: Python
- Homepage: https://www.npmjs.com/package/cctally
- Size: 19.1 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code-toolkit - cctally - per-1% trend. Local web dashboard, terminal UI, forecasts, threshold alerts. Apache-2.0, zero telemetry. | (Companion Apps & GUIs / GateGuard — Fact-Forcing PreToolUse Gate)
README
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)
```bash
brew install omrikais/cctally/cctally
cctally setup
```
### npm
```bash
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
```bash
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.
```bash
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](docs/installation.md) and [docs/configuration.md](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`](https://github.com/ryoppippi/ccusage), and it stays compatible at the level of common CLI flows (`daily`, `monthly`, `weekly`, `session`, `blocks`). Paste from ccusage verbatim: `cctally claude ` is a drop-in for `ccusage claude ` (and `cctally codex ` for `ccusage codex `), 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`](https://github.com/omrikais/cctally/blob/main/bench/README.md).
## Documentation
- [Installation](docs/installation.md): symlinks, status-line wiring, Python version.
- [Configuration](docs/configuration.md): `config.json` shape and week-start rules.
- [Architecture](docs/architecture.md): data flow, caches, week boundaries.
- [Runtime data](docs/runtime-data.md): what lives in `~/.local/share/cctally/`.
- [Command reference](docs/commands/): one page per subcommand.
## License
Apache 2.0. See [`LICENSE`](LICENSE).