claude-finops 0.7.2 → 0.9.0

package/README.md

@@ -8,8 +8,10 @@ It answers, in a few clicks:
 > **What I used → what it cost → why it cost that much → whether it was efficient →
 > what is likely to happen next → and what I should change.**
 
-Everything runs on `127.0.0.1` with the Python standard library. No dependencies, no
-network calls, no data leaves the machine.
+Everything runs on `127.0.0.1` with the Python standard library. No dependencies, and
+no data leaves the machine. No outbound calls except a once-a-day version check
+against the npm registry (disable with `--no-update-check`), and provider APIs only
+if you add a key.
 
 ```bash
 npx claude-finops
@@ -97,9 +99,10 @@ set.
 - **Nothing to learn.** Every screen states its own conclusion in plain English before
   it shows you a chart, and every number carries a badge saying whether it is measured
   or estimated.
-- **Your data stays put.** It binds to `127.0.0.1` and makes no outbound calls. The
-  warehouse lives in `~/.claude-finops`, so upgrading or deleting the package never
-  touches it.
+- **Your data stays put.** It binds to `127.0.0.1`. No outbound calls except a
+  once-a-day version check against the npm registry (disable with
+  `--no-update-check`), and provider APIs only if you add a key. The warehouse lives
+  in `~/.claude-finops`, so upgrading or deleting the package never touches it.
 - **It tells you what to change**, not just what happened — usually with a prompt you
   can paste into Claude Code.
 
@@ -115,7 +118,7 @@ carries one of four badges, and nothing is invented.
 | **Actual** | Read straight out of your transcripts: token counts, timestamps, models, effort, tool calls, file paths, session and project identity. |
 | **Estimated** | Derived. **Every dollar figure is estimated**, because Claude Code transcripts contain token counts but no billed amount. Cost = tokens × the price table in `config/pricing.json`. |
 | **Forecast** | Projected from your history. Assumes the recent pattern continues. |
-| **Recommendation** | A modelled opportunity. Savings estimates hold token usage constant on the alternative and do **not** model output quality. |
+| **Recommendation** | A recommendation grounded in an observed share of spend. No saving is estimated. |
 
 ### Deliberately not fabricated
 
@@ -173,8 +176,9 @@ Two files, both editable without touching code. The server picks up changes to
 ### `config/pricing.json`
 
 Model prices per million tokens, kept strictly separate from usage data so the table
-can be updated as prices change. A model with no entry falls back to
-`default_model_pricing` and is flagged as such in the Model analysis view.
+can be updated as prices change. A `claude-*` model with no entry is priced as
+`unpriced` ($0, flagged as such in the Model analysis view) rather than silently
+billed at another model's rate.
 
 ### `config/settings.json`
 
@@ -287,45 +291,6 @@ place for you to delete once you are happy.
 
 ---
 
-## Running the trial, not just recommending one
-
-The evidence table ends by admitting its own limit: your prompts were never
-randomly assigned to models, so a category can simply have been easier on one of
-them. **Try it →** on any row closes that gap. It pulls prompts you actually
-typed in that category, re-runs them headlessly on the candidate model, and
-prices the result against what they cost the first time.
-
-Nothing runs on its own: a trial spends real money and drives a real agent, so
-it takes two clicks and shows the first-time bill before you commit. Runs happen
-in a scratch directory, and headless Claude cannot ask for permission — so tools
-that need it are denied and counted, and a task that needs your repo will look
-smaller than it is. The verdict says which way it went: *confirmed*, *smaller
-than advertised*, or *history overstated it*.
-
----
-
-## Live model advice
-
-The back-test tells you what to use next time. These tell you mid-session, while
-you can still act on it:
-
-```
-claude-finops --advise               what every running session should switch to
-claude-finops --install-hook         suggest a cheaper model as you send each prompt
-claude-finops --install-statusline   model, context pressure and advice in your statusline
-```
-
-The hook and statusline read the same evidence as the dashboard, cached for an
-hour, and stay quiet unless your own history shows a cheaper model doing that
-category of work without taking more turns. Neither can block or slow a prompt:
-they fail silent and always exit 0. Undo with `--uninstall-hook` /
-`--uninstall-statusline`; your `~/.claude/settings.json` is backed up first.
-
-The Running sessions view shows the same line per live session, with the
-`/model` command ready to copy.
-
----
-
 ## Privacy
 
 `~/.claude-finops/data/finops.db` and the prompt/CSV exports contain **your full prompt text**. The

package/config/pricing.json

@@ -2,19 +2,147 @@
   "_comment": "Model pricing in USD per 1,000,000 tokens. Kept SEPARATE from usage data so it can be updated without touching the dashboard. Any cost derived from these numbers is ESTIMATED, never actual billed cost.",
   "currency": "USD",
   "unit": "per_million_tokens",
-  "updated": "2026-09-18",
-  "source": "user-configurable list price table",
-  "default_model_pricing": {
-    "input": 3.0,
-    "output": 15.0,
-    "cache_write_5m": 3.75,
-    "cache_write_1h": 6.0,
-    "cache_read": 0.3
-  },
+  "updated": "2026-09-28",
+  "source": "Anthropic list prices (platform.claude.com/docs/en/about-claude/pricing, fetched 2026-09-28)",
   "models": {
     "claude-opus-5": {
       "display_name": "Claude Opus 5",
       "tier": "frontier",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "cache_read": 0.5,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-5[fast]": {
+      "display_name": "Claude Opus 5 (fast mode)",
+      "tier": "frontier",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "cache_read": 1.0,
+      "context_window": 1000000,
+      "provider": "anthropic",
+      "_note": "Research-preview fast mode, 2x standard. Selected when usage.speed == 'fast'."
+    },
+    "claude-opus-5-5": {
+      "display_name": "Claude Opus 5.5",
+      "tier": "frontier",
+      "input": 4.0,
+      "output": 20.0,
+      "cache_write_5m": 5.0,
+      "cache_write_1h": 8.0,
+      "cache_read": 0.20,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-5-5[fast]": {
+      "display_name": "Claude Opus 5.5 (fast mode)",
+      "tier": "frontier",
+      "input": 8.0,
+      "output": 40.0,
+      "cache_write_5m": 10.0,
+      "cache_write_1h": 16.0,
+      "cache_read": 0.40,
+      "context_window": 1000000,
+      "provider": "anthropic",
+      "_note": "Research-preview fast mode, 2x standard. Selected when usage.speed == 'fast'."
+    },
+    "claude-sonnet-5": {
+      "display_name": "Claude Sonnet 5",
+      "tier": "balanced",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_write_5m": 2.5,
+      "cache_write_1h": 4.0,
+      "cache_read": 0.2,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-fable-5": {
+      "display_name": "Claude Fable 5",
+      "tier": "frontier",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "cache_read": 1.0,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-fable-5-1": {
+      "display_name": "Claude Fable 5.1",
+      "tier": "frontier",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "cache_read": 0.25,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-4-8": {
+      "display_name": "Claude Opus 4.8",
+      "tier": "frontier",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "cache_read": 0.5,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-4-8[fast]": {
+      "display_name": "Claude Opus 4.8 (fast mode)",
+      "tier": "frontier",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "cache_read": 1.0,
+      "context_window": 1000000,
+      "provider": "anthropic",
+      "_note": "Research-preview fast mode, 2x standard. Selected when usage.speed == 'fast'."
+    },
+    "claude-opus-4-7": {
+      "display_name": "Claude Opus 4.7",
+      "tier": "frontier",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "cache_read": 0.5,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-4-6": {
+      "display_name": "Claude Opus 4.6",
+      "tier": "frontier",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "cache_read": 0.5,
+      "context_window": 1000000,
+      "provider": "anthropic"
+    },
+    "claude-opus-4-5": {
+      "display_name": "Claude Opus 4.5",
+      "tier": "frontier",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "cache_read": 0.5,
+      "context_window": 200000,
+      "provider": "anthropic"
+    },
+    "claude-opus-4-1": {
+      "display_name": "Claude Opus 4.1",
+      "tier": "frontier",
       "input": 15.0,
       "output": 75.0,
       "cache_write_5m": 18.75,
@@ -23,30 +151,30 @@
       "context_window": 200000,
       "provider": "anthropic"
     },
-    "claude-opus-5[1m]": {
-      "display_name": "Claude Opus 5 (1M context)",
+    "claude-opus-4": {
+      "display_name": "Claude Opus 4",
       "tier": "frontier",
-      "input": 22.5,
-      "output": 112.5,
-      "cache_write_5m": 28.125,
-      "cache_write_1h": 45.0,
-      "cache_read": 2.25,
-      "context_window": 1000000,
+      "input": 15.0,
+      "output": 75.0,
+      "cache_write_5m": 18.75,
+      "cache_write_1h": 30.0,
+      "cache_read": 1.5,
+      "context_window": 200000,
       "provider": "anthropic"
     },
-    "claude-sonnet-5": {
-      "display_name": "Claude Sonnet 5",
+    "claude-sonnet-4-6": {
+      "display_name": "Claude Sonnet 4.6",
       "tier": "balanced",
       "input": 3.0,
       "output": 15.0,
       "cache_write_5m": 3.75,
       "cache_write_1h": 6.0,
       "cache_read": 0.3,
-      "context_window": 200000,
+      "context_window": 1000000,
       "provider": "anthropic"
     },
-    "claude-fable-5": {
-      "display_name": "Claude Fable 5",
+    "claude-sonnet-4-5": {
+      "display_name": "Claude Sonnet 4.5",
       "tier": "balanced",
       "input": 3.0,
       "output": 15.0,
@@ -56,8 +184,8 @@
       "context_window": 200000,
       "provider": "anthropic"
     },
-    "claude-fable-5-1": {
-      "display_name": "Claude Fable 5.1",
+    "claude-sonnet-4": {
+      "display_name": "Claude Sonnet 4",
       "tier": "balanced",
       "input": 3.0,
       "output": 15.0,
@@ -67,6 +195,17 @@
       "context_window": 200000,
       "provider": "anthropic"
     },
+    "claude-3-5-haiku": {
+      "display_name": "Claude Haiku 3.5",
+      "tier": "economy",
+      "input": 0.8,
+      "output": 4.0,
+      "cache_write_5m": 1.0,
+      "cache_write_1h": 1.6,
+      "cache_read": 0.08,
+      "context_window": 200000,
+      "provider": "anthropic"
+    },
     "claude-haiku-4-5-20251001": {
       "display_name": "Claude Haiku 4.5",
       "tier": "economy",
@@ -225,6 +364,9 @@
       "_note": "Cursor bills by subscription and doesn't record the model locally: no cost is estimated"
     }
   },
+  "aliases": {
+    "claude-haiku-4-5": "claude-haiku-4-5-20251001"
+  },
   "_sources": {
     "openai": "https://developers.openai.com/api/docs/pricing (standard tier, 2026-09-18)",
     "google": "https://ai.google.dev/gemini-api/docs/pricing (paid tier, 2026-09-18)"

package/config/settings.json

@@ -41,17 +41,23 @@
       "frontier"
     ],
     "low_output_ratio_vs_median": 0.4,
+  "tool_loop_calls": 40,
+  "poor_cache_min_writes": 500000,
     "_low_output_note": "Sessions are flagged when their output/billable ratio falls below this fraction of YOUR median session ratio, rather than an absolute number, because a healthy ratio depends on how agentic your workload is."
   },
+  "hygiene": {
+    "_comment": "Context sizes (prompt-side tokens) the hygiene view reports spend above. Observed shares only; no saving is estimated from them.",
+    "context_thresholds": [100000, 150000]
+  },
   "anomaly": {
+    "_comment": "session_ratio is measured against the MEDIAN session, not the mean: session sizes are right-skewed enough that a mean lets the outliers inflate their own baseline. Session token counts are heavy-tailed, so max_session_outliers, not the ratio, is what keeps the list short and leaves room for the other anomaly types. daily_robust_z is a threshold on a median/MAD robust z-score (MAD scaled by 1.4826 to estimate a stdev), not the plain daily_zscore: unpriced $0 days from agents with no pricing data would otherwise pollute a mean/stdev baseline.",
     "daily_zscore": 2.0,
     "daily_ratio": 2.0,
-    "session_ratio": 3.0
+    "daily_robust_z": 3.5,
+    "session_ratio": 20.0,
+    "max_session_outliers": 5
   },
   "scorecard": {
-    "_comment": "Reference points the 0-100 dimension scores are graded against. Derived from your own data by default; override to hold yourself to a different bar.",
-    "target_output_ratio": 0.0088,
-    "target_cost_per_1k_output_usd": 0.3,
-    "frontier_cost_share_allowance_pct": 40
+    "_comment": "The scorecard has no targets to configure: its three dimensions (Context share, Cache break-even, Budget adherence) are each measured directly from your transcripts, except budget adherence which needs a budget configured above."
   }
 }

package/finops/actions.py

@@ -18,7 +18,7 @@ import urllib.request
 import uuid
 from collections import defaultdict
 
-from .analytics import DB_PATH, ROOT
+from .paths import DB_PATH, ROOT
 from .etl import DEFAULT_SOURCE, Loader
 
 HOME = os.path.expanduser("~")

package/finops/agents.py

@@ -33,7 +33,8 @@ def _cursor_state_db():
 
 AGENTS = {
     "claude": {"name": "Claude Code", "data": "full",
-               "note": "Tokens, model, cost, prompts and tool calls per request."},
+               "note": "Tokens, model, cost, prompts and tool calls per request. "
+                       "Includes Claude desktop app (Cowork) sessions when present."},
     "codex": {"name": "Codex", "data": "tokens",
               "paths": [os.path.join(HOME, ".codex", "sessions")],
               "note": "Tokens and model per turn. Cost estimated at OpenAI API list prices; "