cctally 1.57.1 → 1.58.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.58.0] - 2026-06-30
+
+### Added
+- Embedded pricing for Claude Sonnet 5 (`claude-sonnet-5`) so its sessions are costed correctly instead of falling back to $0 as an unknown model. The rate is the standard $3/$15 per-MTok price (flat across the full 1M-token context window, identical to Claude Sonnet 4.6) — the durable rate that takes effect after Anthropic's introductory $2/$10 pricing ends 2026-08-31 — and the pricing snapshot date is bumped to 2026-07-01. LiteLLM has no Sonnet 5 entry yet, so the table is simply ahead of it (not flagged as drift by `pricing-check`).
+
+### Changed
+- Dashboard at-a-glance redesign: the weekly Used % now dominates as a full-width hero strip — replacing the five header stats and the Current Week grid card — flanked by four spelled-out metrics (cost / 1%, Forecast, 5-hour, vs last week) and a freshness chip, and opening the rich Current Week modal on click. The panel grid is now two-tier: uniform-height summary tiles (Forecast, Weekly, Monthly, Blocks, Alerts) pack into a responsive auto-fit row above full-width data cards (Sessions, Trend, Projects, Daily, Cache Report), with within-tier drag-and-keyboard reorder that cannot cross tiers, eliminating the old forced two-column grid's dead space and roughly halving the page height. Weekly/Monthly/Blocks compact to their three most-recent rows (full history stays one tap away in each panel's modal), Forecast becomes a calm verdict tile, the empty Recent Alerts state collapses to a single line, and on mobile the hero stacks with a 2×2 metric grid while the sticky top bar collapses to one ≤64px row that reveals a condensed Used%/reset readout once you scroll past the hero (#248).
+- Dashboard styling is now built entirely on the shared design tokens: every `border-radius`, `box-shadow`, and accent colour across the dashboard chrome (rgba *and* hex) resolves to the radius/shadow/accent token scale instead of a raw literal, with a small documented allowlist for intentional data-viz and bespoke values. A new global lint keeps it that way — it fails the build if any orphan literal creeps back into the dashboard CSS (the conversation viewer, which owns its own token story, is excluded). There is no visible change; this is the maintainability follow-through on the #247 token foundation (#255).
+- Dashboard cards now wear a calm, neutral chrome: borders, hover elevation, header dividers, the keyboard focus ring, and every panel header title read in one consistent neutral treatment instead of eleven competing accent colours, and accent colour is reserved for genuine state — Cache Report's healthy/anomaly header and the Forecast verdict keep their meaningful hues while healthy cards stay quiet; the look is built on a new radius/shadow/type-scale design-token foundation, and Recent Sessions now caps its height and scrolls internally with its column headers pinned (#247).
+- Dashboard cards read truer at a glance: when every visible Recent Session uses the same model (the common single-model case) the redundant per-row model pills collapse to a single "all · model" caption and the reclaimed width goes to the Project column so names render in full instead of truncating; the Weekly, Monthly, and Blocks model-split bars gain a compact inline legend (model dot + short name + %, with a "+N" overflow) so the breakdown is legible at a glance and on touch instead of hiding in a hover tooltip; the panel drag-to-reorder grip is now visible at rest on desktop and brightens on hover (it previously appeared only on touch) so reordering is discoverable without hovering; the footer keyboard-hint strip is hidden on touch devices where it carries no meaning; and the Current Week modal's early-week progress gauge no longer crowds its per-percent milestone ticks into a sliver below 15% used (#249).
+
+### Fixed
+- Dashboard Projects panel on mobile no longer clips a four-figure project cost — the cost column is now content-sized so a value like $1,234.56 renders at full precision (the project name ellipsizes first instead). The Forecast panel's verdict chip now shows the glyph that matches its state — ✓ when healthy, ⚠ on warn, ⛔ when over — instead of always painting a warning triangle even on a perfectly healthy forecast (#248).
+- Conversation viewer: navigating away from (or closing) a conversation while a jump-to-message is still settling no longer leaves the reader running layout-measurement animation frames against the now-unmounted view — the quiesce wait loop now stops the instant the jump is cancelled. This was invisible in normal use but surfaced as cross-test flakiness in the dashboard test suite, where a leaked frame ran after the test environment was torn down and intermittently failed the full parallel run (#256).
+- Dashboard on mobile: form controls (the Recent Sessions filter/search, the Settings inputs and dropdowns, and the Cache Report threshold popover) no longer trigger iOS Safari's auto-zoom on focus, and the smallest primary data text in Sessions, Projects, and Trend is raised to a legible 14px floor (#247).
+- Dashboard Current Week card no longer shows the snapshot freshness twice — the duplicate "Last snapshot" footer is gone and a single header freshness chip is now the one source of truth, rendered in a calm neutral tone when fresh and a loud amber ⚠ only when the data is genuinely stale (#247).
+
+### Documentation
+- README rewritten as a feature-led landing page: a per-capability tour (live dashboard, conversation viewer, cost-per-1% trend, forecast & budget, threshold alerts, 5-hour analytics, live TUI, shareable reports, Codex parity, diagnostics) replaces the prior single bullet list, with a dedicated conversation-viewer showcase and two new screenshots (desktop reader + mobile phone). All marketing screenshots were regenerated against the current model lineup (Opus 4.8 and Fable 5), and the stale "nine-panel" dashboard description is corrected to the actual eleven panels.
+
 ## [1.57.1] - 2026-06-28
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <strong>Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.</strong>
+  <strong>Local-first usage tracker for Claude Code on Pro/Max - live dashboard, conversation viewer, weekly cost-per-percent trend, quota forecast, and threshold alerts. ccusage-compatible.</strong>
 </p>
 
 <p align="center">
@@ -16,59 +16,46 @@
   <a href="https://github.com/omrikais/cctally/stargazers"><img src="https://img.shields.io/github/stars/omrikais/cctally.svg" alt="GitHub stars"></a>
 </p>
 
-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.
+Claude Code's Pro/Max plans meter you on a weekly quota, but the only signal you get is a percentage that creeps up until you cap. `cctally` turns that percentage into something you can act on: it reads your local session logs, computes cost in-process, and shows you **how much each percent of quota is actually costing you, whether you're on track to cap this week, and exactly where the spend is going** - across a live web dashboard, a read-only conversation viewer, and a full set of CLI reports. Everything runs locally against your own `~/.claude` data. No account, no API key, no telemetry, nothing leaves your machine.
 
 <p align="center">
   <img src="docs/img/dashboard-desktop.png" alt="cctally dashboard, desktop view" width="900">
 </p>
 
-## Installation
+## Quick start
 
 **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.
+# Homebrew (macOS / Linux)
+brew install omrikais/cctally/cctally && cctally setup
 
-### From source
+# …or npm
+npm install -g cctally && cctally setup
 
-```bash
-git clone https://github.com/omrikais/cctally
-cd cctally
-./bin/cctally setup
+# …or 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` symlinks the binaries into `~/.local/bin/`, adds three additive hooks to `~/.claude/settings.json` (it 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. The npm install needs Python 3 on `PATH` - if setup reports "python3 not found", install it (`brew install python` on macOS) and re-run.
 
 ```bash
 cctally setup --status     # verify hooks + symlinks
-cctally daily              # cost-by-day, your first table
+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).
+For status-line integration and tuning, see [docs/installation.md](docs/installation.md) and [docs/configuration.md](docs/configuration.md).
 
-## What it looks like
+## The live dashboard
 
-### Dashboard
+`cctally dashboard` serves a web app at `localhost:8789` that updates live as you work - no refresh, no polling. Eleven panels cover the whole picture: **current week**, **forecast**, **$/1% trend**, **recent sessions**, **weekly**, **monthly**, **5-hour blocks**, **daily heatmap**, **projects**, **cache report**, and **recent alerts**. Any panel expands into a focused view, sessions are filterable and searchable, and a settings drawer tunes alerts and display options on the fly. It runs only on your own machine by default; one flag opens it to the other devices on your network when you want that.
 
 <table>
   <tr>
     <td>
       <img src="docs/img/dashboard-modal.png" alt="Dashboard with trend modal open">
-      <br><em>Any panel expands into a focused view. The trend modal shows twelve weeks of cost per percent.</em>
+      <br><em>Any panel expands into a focused view - here, twelve weeks of cost per percent.</em>
     </td>
     <td>
       <img src="docs/img/dashboard-warn.png" alt="Dashboard in warn state">
@@ -78,12 +65,34 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
   <tr>
     <td colspan="2" align="center">
       <img src="docs/img/dashboard-mobile.png" alt="Dashboard on phone" width="350">
-      <br><em>The same dashboard on your phone.</em>
+      <br><em>The same dashboard, reflowed for your phone.</em>
     </td>
   </tr>
 </table>
 
-### CLI tables
+See [docs/commands/dashboard.md](docs/commands/dashboard.md).
+
+## Conversation viewer ⭐
+
+The dashboard's **Conversations** tab is a read-only reader for your Claude Code transcripts - your local session history, rendered the way you'd actually want to review it. A searchable rail lists every conversation with its project, branch, model chips, and cost; the reader shows the full turn-by-turn flow with thinking blocks, tool calls (with diffs and command output), and a per-turn cost-and-token breakdown. Parallel **subagent threads** render as their own nested threads, an outline pane jumps you to any turn, and an in-conversation find bar plus a faceted full-text search (prompts, assistant text, tools, thinking) make a month of sessions navigable. The open conversation **live-tails** as you work, updating within a second.
+
+It only reads your transcripts - it never changes them - and everything stays on your own machine. Nothing is uploaded, and the viewer is reachable only from your computer unless you choose to share the dashboard with your network.
+
+<p align="center">
+  <img src="docs/img/conversation-reader.png" alt="Conversation viewer: rail, threaded reader, and outline" width="900">
+  <br>
+  <em>Rail, threaded reader with tool cards and a subagent thread, and the jump-to outline.</em>
+</p>
+
+<p align="center">
+  <img src="docs/img/conversation-mobile.png" alt="Conversation viewer on a phone" width="300">
+  <br>
+  <em>The same reader on your phone.</em>
+</p>
+
+## Cost per 1% of quota
+
+The signature view. `cctally report` reframes each subscription week's spend as **dollars per percent of quota used**, so you can see your spending efficiency trend week over week - and whether this week is pulling above or below the line - instead of staring at a raw percentage. Persisted to SQLite, so the comparison survives across runs.
 
 <p align="center">
   <img src="docs/img/cli-report.svg" alt="cctally report: $ per 1% weekly trend">
@@ -91,19 +100,39 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
   <em>Weekly cost as dollars per percent of quota, with the delta against the prior week.</em>
 </p>
 
+See [docs/commands/report.md](docs/commands/report.md).
+
+## Forecast & budget
+
+`cctally forecast` projects where your weekly percentage lands at the next reset - using both a week-average and a recent-24h rate - and tells you the daily $/% budget you'd need to stay under the 100% and 90% ceilings. When the data is thin it says so (`LOW CONF`) rather than guessing.
+
 <p align="center">
   <img src="docs/img/cli-forecast.svg" alt="cctally forecast: will I cap this week?">
   <br>
   <em>Projected percent at the weekly reset, plus the daily budget to stay under the cap.</em>
 </p>
 
+For dollar budgets, `cctally budget` tracks an equivalent-vs-actual spend target over a configurable calendar period - per vendor, for both Claude and Codex - with a pace projection and an `ok`/`warn`/`over` verdict. See [docs/commands/forecast.md](docs/commands/forecast.md) and [docs/commands/budget.md](docs/commands/budget.md).
+
+## Threshold alerts
+
+Get a native desktop notification the moment you cross a percent milestone, so a runaway week can't sneak up on you. Alerts fire on weekly percent, 5-hour blocks, and budget thresholds, with three severity levels (info / warn / critical) and native popups on macOS and Linux - or run a command of your own. `cctally alerts test` confirms it's wired up. See [docs/commands/alerts.md](docs/commands/alerts.md).
+
+## 5-hour analytics
+
+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, not a re-sizable guess - with model and project rollups and cross-reset flags, and `cctally five-hour-breakdown` drills into the per-percent milestones inside a single block.
+
 <p align="center">
   <img src="docs/img/cli-five-hour-blocks.svg" alt="cctally five-hour-blocks: 5h analytics with model breakdown">
   <br>
-  <em>Each 5-hour window, broken down by model.</em>
+  <em>Each 5-hour window, with rollup totals and 7-day drift.</em>
 </p>
 
-### Live terminal
+See [docs/commands/blocks.md](docs/commands/blocks.md) and [docs/commands/five-hour-blocks.md](docs/commands/five-hour-blocks.md).
+
+## Live terminal UI
+
+Prefer to stay in the terminal, or working over SSH? `cctally tui` shows the same live data as a refreshing terminal dashboard. It's the one feature that needs the optional `rich` library; every other command runs on a plain Python install with nothing else to set up.
 
 <p align="center">
   <img src="docs/img/cli-tui.svg" alt="cctally tui: live terminal dashboard">
@@ -111,29 +140,32 @@ For status-line integration, alerts, and configuration, see [docs/installation.m
   <em>The same data in the terminal, refreshed live.</em>
 </p>
 
-## What cctally adds
+See [docs/commands/tui.md](docs/commands/tui.md).
+
+## Shareable reports
+
+All eight reporting commands (`report`, `daily`, `monthly`, `weekly`, `forecast`, `project`, `five-hour-blocks`, `session`) can render to shareable Markdown, HTML, or SVG with `--format`, a light/dark `--theme`, and `--output` / `--copy` / `--open`. Project names anonymize by default (`--reveal-projects` opts in), so you can post a snapshot without leaking where you work. See [docs/commands/share.md](docs/commands/share.md).
+
+## Codex parity
+
+If you also use OpenAI's Codex CLI, `cctally codex daily / monthly / session` are drop-ins for `ccusage codex daily / monthly / session`, reading from `~/.codex/sessions/`. The flat `codex-*` forms (drop-ins for the standalone `ccusage-codex` binary) stay as aliases, and `cctally codex weekly` adds a subscription-week rollup that upstream doesn't have. See [docs/commands/codex.md](docs/commands/codex.md).
+
+## Diagnostics & upkeep
+
+`cctally doctor` gives you a read-only health check - install, hooks, sign-in, database, data freshness, pricing, and safety - and the same status shows up in the dashboard. `cctally pricing-check` warns you when the built-in model pricing is getting stale, `cctally db` manages the local database, and `cctally update` keeps your install current. The local cache is always safe to delete or rebuild.
 
-`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 <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:
+## A faster, local-first ccusage
 
-- **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.
+`cctally` started as a local replacement for [`ccusage`](https://github.com/ryoppippi/ccusage) and stays compatible at the level of common flows: `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. Paste your ccusage commands verbatim - then reach for the dashboard, forecast, trend, conversation viewer, and alerts that ccusage doesn't have.
 
-**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]
+It's also fast. Pricing is built in and computed in-process from a local SQLite cache, with no external tools to spawn. First table 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]
 
 <!--
   Footnote target uses an absolute URL because GitHub's relative-link
   rewriter doesn't traverse into GFM footnote `<li>` content; on the
   repo home page (`/omrikais/cctally`, no trailing slash) the browser
   would resolve `bench/README.md` against the page URL and produce
-  `/omrikais/bench/README.md` — a broken path. Regular paragraph links
+  `/omrikais/bench/README.md` - a broken path. Regular paragraph links
   are unaffected.
 -->
 [^bench]: Methodology and reproduction: [`bench/README.md`](https://github.com/omrikais/cctally/blob/main/bench/README.md).

package/bin/_lib_pricing.py

@@ -53,7 +53,7 @@ def _chip_for_model(name: str) -> str:
 # Date the embedded pricing snapshots below were last verified against
 # vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
 # is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
-PRICING_SNAPSHOT_DATE = "2026-06-10"
+PRICING_SNAPSHOT_DATE = "2026-07-01"
 PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
 
 # Canonical machine-readable pricing source (Claude values + Codex values).
@@ -71,11 +71,17 @@ PRICING_DRIFT_ALLOWLIST: list[dict] = []
 
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-06-10 (see PRICING_SNAPSHOT_DATE)
+# - Captured: 2026-07-01 (see PRICING_SNAPSHOT_DATE)
 # - Verified by maintainer against docs.claude.com/en/docs/about-claude/pricing;
 #   update in PRs touching this table.
 #   2026-06-10: added claude-fable-5 ($10/$50 per MTok; 1M context, no
 #   long-context premium) — issue #172.
+#   2026-07-01: added claude-sonnet-5 ($3/$15 per MTok; 1M context, flat-rate
+#   across the full window — no long-context premium, same shape as
+#   claude-sonnet-4-6). Embedded the STANDARD rate, not the $2/$10 introductory
+#   rate in effect through 2026-08-31, to match what LiteLLM will publish and
+#   the durable post-cutover price. LiteLLM has no sonnet-5 entry yet, so the
+#   table is ahead_of_litellm (not a drift finding).
 CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
     "claude-3-5-haiku-20241022": {
         "input_cost_per_token": 8e-07,
@@ -267,6 +273,12 @@ CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
         "cache_creation_input_token_cost": 3.75e-06,
         "cache_read_input_token_cost": 3e-07,
     },
+    "claude-sonnet-5": {
+        "input_cost_per_token": 3e-06,
+        "output_cost_per_token": 1.5e-05,
+        "cache_creation_input_token_cost": 3.75e-06,
+        "cache_read_input_token_cost": 3e-07,
+    },
 }
 
 _unknown_model_warnings: set[str] = set()