README.md

Understand Claude Code and Codex spend: a local dashboard, conversation viewer, and CLI reports for your subscription quota.

Your Claude Code plan meters you with a percentage that creeps up all week. cctally reads your local session logs and turns that percentage into dollars: what each percent of quota costs you, whether you are on track to cap before the reset, and where the spend is going. It does the same for OpenAI's Codex CLI. Everything runs on your own machine, against your own data. No account, no API key, and nothing is uploaded.

Claude cost coverage: Claude dollar and token totals are transcript-derived lower bounds, not exact /usage billing totals. Claude Code can bill title-generation and prompt-suggestion/side-query requests without retaining usable model/token fields. cctally does not guess the missing amount. Codex accounting uses a different retained source and is unaffected.

Latest stable: v1.95.5 (2026-08-09)

• Dashboard share-digest validation now pins the template artifact clock as well as the dashboard data clock, so two equivalent renders cannot fail Linux CI merely because their frontmatter and footer crossed a one-second wall-clock boundary.

Quick start

Requirements: Python 3.11+, macOS or Linux, and Claude Code and/or OpenAI's Codex CLI installed and run at least once.

# Homebrew (macOS / Linux)
brew install omrikais/cctally/cctally && cctally setup

# or npm
npm install -g cctally && cctally setup

# or from source
git clone https://github.com/omrikais/cctally && cd cctally && ./bin/cctally setup

The reporting commands work immediately on your existing logs, before any setup. Running cctally setup once adds the Claude hooks and native Codex handlers that keep each provider's local quota observations current as you work.

cctally daily              # cost by day: your first table
cctally dashboard          # opens http://127.0.0.1:8789
cctally setup --status     # verify the install

Install details (symlinks, PATH, Python version) live in docs/installation.md. Every release ships to an opt-in beta channel first; see docs/commands/update.md.

The live dashboard

cctally dashboard serves a local web app that updates live as you work, with no refresh and no polling. Panels cover the current week, the forecast, the cost trend, sessions, 5-hour blocks, projects, and alerts. Any panel expands into a focused view, sessions are searchable, and every report can be exported as shareable Markdown, HTML, or SVG with project names anonymized by default. It stays on your machine unless you choose to open it to your network.

Any panel expands into a focused view: here, twelve weeks of cost per percent.	When the forecast projects a cap before the weekly reset, the modal turns amber.
The same dashboard, reflowed for your phone.

See docs/commands/dashboard.md.

Conversation viewer

The dashboard's Conversations tab is a read-only reader for your Claude Code and Codex transcripts. A searchable rail lists every conversation with its source, project, branch, models, and cost; the reader shows the full turn-by-turn flow with reasoning, tool calls, and per-turn cost. Subagent runs render as nested threads, and the open conversation live-tails as you work. It never modifies your transcripts, and it never leaves your machine.

The same reader on your phone.

Cost per 1% of quota

The signature view. cctally report reframes each week's spend as dollars per percent of quota used, so you can watch your spending efficiency trend week over week instead of staring at a raw percentage.

See docs/commands/report.md.

Forecast, budget, and alerts

cctally forecast projects where your weekly percentage lands at the next reset and tells you the daily budget that keeps you under the cap. cctally budget tracks a dollar target per provider over a calendar period. Native desktop notifications fire the moment you cross a percent, 5-hour, or budget threshold, so a runaway week cannot sneak up on you.

See docs/commands/forecast.md, docs/commands/budget.md, and docs/commands/alerts.md.

5-hour blocks

Claude Code's quota also runs on rolling 5-hour windows. cctally blocks and cctally five-hour-blocks break usage down per window, anchored to the real API resets, with model and project rollups.

See docs/commands/blocks.md and docs/commands/five-hour-blocks.md.

Codex

If you also use OpenAI's Codex CLI, cctally tracks it with the same depth. cctally codex daily, monthly, and session are drop-in replacements for the ccusage codex commands, reading from your local ~/.codex/sessions/. cctally codex weekly adds a subscription week rollup, and cctally codex quota shows your native Codex rate limit windows.

See docs/commands/codex.md and docs/commands/codex-quota.md.

Terminal UI

Prefer to stay in the terminal, or working over SSH? cctally tui is the Claude-only, bugfix-only terminal dashboard. It remains supported, but it does not track newer web-dashboard capabilities and is not part of cross-provider parity. It is the one feature that needs the optional rich library; everything else runs on a plain Python install.

See docs/commands/tui.md.

ccusage compatibility

cctally started as a local replacement for ccusage and stays drop-in compatible: cctally claude <cmd> and cctally codex <cmd> accept your ccusage commands verbatim. It is also fast: first table on 30 days of session data took about 2.6 seconds against about 31 seconds for ccusage (about 12x, measured 2026-05-05; methodology in bench/README.md).

Privacy

Everything runs locally against your own ~/.claude and ~/.codex data; session content is never uploaded. The only telemetry is an anonymous, opt-out install-count beat (a rotating one-way token, the version, and a coarse OS family, at most once a day). Turn it off any time with cctally telemetry off. The full transparency page is docs/telemetry.md.

Documentation

• Installation: symlinks, status-line wiring, Python version.
• Configuration: every setting cctally config accepts, its default, and whether the dashboard can change it.
• The config.json file: file shape, reserved collector keys, week-start rules.
• Architecture: data flow, caches, week boundaries.
• Telemetry: the anonymous install-count beat, in full.
• Command reference: one page per subcommand.

License

Apache 2.0. See LICENSE.