claude-finops 0.14.0 → 0.15.1

package/README.md

@@ -347,6 +347,20 @@ Everything the app writes lives outside the install folder, in one state directo
   secrets.local.json      provider API keys (0600)
 ```
 
+Days, "today" and the billing period follow this computer's time zone (Claude Code
+stamps transcripts in UTC; finops converts them). Set `CLAUDE_FINOPS_TZ` to an IANA name
+such as `Asia/Kolkata` to use another one, then press **Sync**.
+
+Claude Code deletes transcripts older than its `cleanupPeriodDays` (30 by default). A
+sync keeps the sessions it already had when their transcript disappears, re-costed at
+current prices, so your history outlives that cleanup. If you delete transcripts on
+purpose and want them gone from the dashboard too, set
+`"history": {"keep_deleted_transcripts": false}` in `settings.local.json`.
+
+While the dashboard runs it re-reads your transcripts by itself once the data is an hour
+old, so recent days don't read as idle. `CLAUDE_FINOPS_AUTOSYNC_MINUTES` changes the
+interval; `0` turns it off and leaves only the **Sync** button.
+
 Set `CLAUDE_FINOPS_HOME=/some/path` to put it elsewhere. The install folder holds
 only code and the shared defaults in `config/`, so it can be replaced on upgrade —
 or shipped as a package — without touching your data. An older in-tree `data/`
@@ -443,6 +457,29 @@ files on Windows.
 - **Install** under Live warnings (Budgets, block ③, or `--install-guard`) adds one `PreToolUse` hook entry to
   `~/.claude/settings.json`, keeping a `.finops-backup` copy. Your other hooks are left
   alone, and uninstalling removes only that entry.
+- **Start experiment** (Subagent models) adds `env.CLAUDE_CODE_SUBAGENT_MODEL` to
+  `~/.claude/settings.json`, keeping a `.finops-backup` copy, after showing you the exact change.
+  It won't overwrite a value you set yourself. **Stop** removes it only if it still holds the
+  value finops wrote.
+
+---
+
+## Subagent models
+
+Subagents are the one place a model switch costs no cache rewrite: each run starts its own cache,
+and Claude Code lets you choose its model. The **Subagent models** page (sidebar, Optimize):
+
+- **Headline:** what subagents cost and their share of your Claude Code spend. That share is the
+  most routing could ever save, even if every run were free.
+- **By type and model:** each subagent type, the models it ran on, and the median cost, turns,
+  output and context per run. Measured from runs that happened, never repriced, and no savings
+  total. A cheaper model is suggested only when both models have at least `subagents.min_runs`
+  runs of that type (5, in `config/settings.json`) and the cheaper one cost less per run. Your own
+  agent files get the exact `model:` line to add; built-in types point to an experiment. Forks get
+  context advice instead, since they always use your conversation's model and context.
+- **Experiment:** run subagents on one model (`haiku`, `sonnet`, `opus` or `fable`) for a while,
+  then compare each type's runs before and after the start. Before is the same length of time
+  just before it, at most 30 days. Runs that used another model anyway are counted separately.
 
 ---
 
@@ -475,7 +512,7 @@ Besides Claude Code, the warehouse loads every other coding agent it finds on th
 |---|---|---|
 | Codex | `~/.codex/sessions` | Tokens + model per turn; cost at OpenAI list price |
 | Gemini CLI | `~/.gemini/tmp/*/chats` | Tokens + model per reply; cost at Gemini list price |
-| Cursor | `~/.cursor/projects/*/agent-transcripts`, Cursor IDE `state.vscdb` (read-only) | Prompts + tool calls; tokens only where Cursor stored them; no model, not priced |
+| Cursor | Cursor IDE `state.vscdb` (read-only) | Prompts, times and tokens as the IDE stored them; no model, not priced. Agent transcripts are skipped: they carry no times or tokens |
 
 Pick agents with the chips at the top: click for one, Cmd/Ctrl-click to combine, **All** for
 everything. Every page follows the selection, and **Agents** shows them side by side.

package/config/model_compare.json

@@ -1,9 +1,11 @@
 {
   "_comment": "Qualitative 1-5 ratings for the Compare view. Judgement from model size, age and known behaviour in agentic coding. Not benchmark scores; edit freely. Keys match model ids in pricing.json or ids in free_models.json.",
   "ratings": {
+    "claude-fable-5-1":          {"tools": 5, "reasoning": 5, "multifile": 5, "speed": "Slower; long turns", "best_for": "The hardest problems; priced well above Opus"},
+    "claude-opus-5-5":           {"tools": 5, "reasoning": 5, "multifile": 5, "speed": "Fast", "best_for": "Hard bugs, architecture, reviews; cheaper than Opus 5"},
     "claude-opus-5":             {"tools": 5, "reasoning": 5, "multifile": 5, "speed": "Fast", "best_for": "Hard bugs, architecture, reviews"},
-    "claude-sonnet-5":           {"tools": 5, "reasoning": 4, "multifile": 5, "speed": "Fast", "best_for": "Everyday coding: best value"},
-    "claude-fable-5-1":          {"tools": 5, "reasoning": 4, "multifile": 4, "speed": "Fast", "best_for": "Same price tier as Sonnet"},
+    "claude-sonnet-5-5":         {"tools": 5, "reasoning": 4, "multifile": 5, "speed": "Fast", "best_for": "Everyday coding: best value"},
+    "claude-sonnet-5":           {"tools": 5, "reasoning": 4, "multifile": 5, "speed": "Fast", "best_for": "Everyday coding (previous Sonnet)"},
     "claude-haiku-4-5-20251001": {"tools": 4, "reasoning": 3, "multifile": 3, "speed": "Fastest", "best_for": "Lookups, Explore subagents, small edits"},
     "qwen-openrouter":           {"tools": 3, "reasoning": 3, "multifile": 3, "speed": "Medium, throttled on free tier", "best_for": "Free general coding, if sending code to OpenRouter is OK"},
     "qwen38-local":              {"tools": 3, "reasoning": 3, "multifile": 3, "speed": "Needs 32 GB+ RAM", "best_for": "Strongest local option on a big machine"},

package/config/pricing.json

@@ -2,8 +2,8 @@
   "_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-28",
-  "source": "Anthropic list prices (platform.claude.com/docs/en/about-claude/pricing, fetched 2026-09-28)",
+  "updated": "2026-10-02",
+  "source": "Anthropic list prices (platform.claude.com/docs/en/about-claude/pricing, fetched 2026-09-28; Sonnet 5.5 added 2026-10-02); OpenAI (developers.openai.com/api/docs/pricing) and Google (ai.google.dev/gemini-api/docs/pricing) checked 2026-10-02",
   "models": {
     "claude-opus-5": {
       "display_name": "Claude Opus 5",
@@ -51,6 +51,17 @@
       "provider": "anthropic",
       "_note": "Research-preview fast mode, 2x standard. Selected when usage.speed == 'fast'."
     },
+    "claude-sonnet-5-5": {
+      "display_name": "Claude Sonnet 5.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-sonnet-5": {
       "display_name": "Claude Sonnet 5",
       "tier": "balanced",
@@ -311,7 +322,7 @@
       "provider": "google",
       "input": 0.3,
       "output": 2.5,
-      "cache_read": 0.075,
+      "cache_read": 0.03,
       "cache_write_5m": 0.3,
       "cache_write_1h": 0.3,
       "context_window": 1048576,
@@ -323,7 +334,7 @@
       "provider": "google",
       "input": 1.25,
       "output": 10.0,
-      "cache_read": 0.3125,
+      "cache_read": 0.125,
       "cache_write_5m": 1.25,
       "cache_write_1h": 1.25,
       "context_window": 1048576,
@@ -335,7 +346,7 @@
       "provider": "google",
       "input": 1.5,
       "output": 9.0,
-      "cache_read": 0.375,
+      "cache_read": 0.15,
       "cache_write_5m": 1.5,
       "cache_write_1h": 1.5,
       "context_window": 1048576
@@ -346,7 +357,7 @@
       "provider": "google",
       "input": 0.75,
       "output": 3.75,
-      "cache_read": 0.1875,
+      "cache_read": 0.075,
       "cache_write_5m": 0.75,
       "cache_write_1h": 0.75,
       "context_window": 1048576,

package/config/settings.json

@@ -39,6 +39,14 @@
     "projects": {},
     "sessions": {}
   },
+  "history": {
+    "_comment": "Claude Code deletes old transcripts (cleanupPeriodDays, 30 days by default). With keep_deleted_transcripts on, a sync keeps the sessions it already had instead of dropping them; turn it off if you delete transcripts on purpose and want them gone from the dashboard too.",
+    "keep_deleted_transcripts": true
+  },
+  "subagents": {
+    "_comment": "Subagent models page: a cheaper model is only suggested, and an experiment only compared, once each side has at least min_runs subagent runs.",
+    "min_runs": 5
+  },
   "waste_rules": {
     "long_prompt_chars": 6000,
     "large_context_tokens": 150000,

package/finops/actions.py

@@ -127,7 +127,9 @@ def sync(log, source=DEFAULT_SOURCE):
     """Rebuild the warehouse into a temp file, then swap it in (the dashboard keeps serving)."""
     tmp = DB_PATH + ".sync"
     log("Reading Claude transcripts…")
-    Loader(db_path=tmp, source=source).build(verbose=False)
+    # the live warehouse is the "previous" one: sessions whose transcripts were deleted
+    # since are carried into the new build (history.keep_deleted_transcripts)
+    Loader(db_path=tmp, source=source, keep_from=DB_PATH if os.path.exists(DB_PATH) else None).build(verbose=False)
     con = sqlite3.connect(tmp)
     con.execute("PRAGMA wal_checkpoint(TRUNCATE)")
     n = con.execute("SELECT COUNT(*) FROM requests").fetchone()[0]
@@ -210,6 +212,7 @@ def free_models():
             have_model = os.path.exists(os.path.join(KEY_DIR, "openrouter.key"))
         fits = not m.get("min_ram_gb") or ram is None or ram >= m["min_ram_gb"]
         out.append({**m, "installed": installed and have_model, "launcher": launcher,
+                    "downloaded": bool(have_model) and m["provider"] == "ollama",
                     "fits_ram": fits, "ram_gb": round(ram or 0), "free_disk_gb": round(disk)})
     return {"models": out, "ollama_installed": bool(_ollama_bin()), "os": OS_NAME,
             "ollama_running": pulled is not None, "bin_on_path": _on_path(BIN_DIR),
@@ -236,11 +239,18 @@ def free_model_plan(mid):
         if ram and m.get("min_ram_gb") and ram < m["min_ram_gb"]:
             steps.append({"do": f"Warning: this model wants {m['min_ram_gb']} GB RAM and this "
                                 f"machine has {ram:.0f} GB. It may be very slow.", "warn": True})
-        if m.get("download_gb") and _free_disk_gb() < m["download_gb"] + 2:
-            return {"model": m, "blocked": f"Needs ~{m['download_gb']} GB free disk; only "
-                    f"{_free_disk_gb():.0f} GB free."}
-        steps.append({"do": f"Download {m['model']} (~{m['download_gb']} GB) with ollama pull",
-                      "consent": True})
+        pulled = _ollama_running() or []
+        have = any(n == m["model"] or n == m["model"] + ":latest" for n in pulled)
+        if have:
+            # ollama pull on a model you already have only checks it is current
+            steps.append({"do": f"{m['model']} is already downloaded; ollama pull only checks it is current",
+                          "consent": False})
+        else:
+            if m.get("download_gb") and _free_disk_gb() < m["download_gb"] + 2:
+                return {"model": m, "blocked": f"Needs ~{m['download_gb']} GB free disk; only "
+                        f"{_free_disk_gb():.0f} GB free."}
+            steps.append({"do": f"Download {m['model']} (~{m['download_gb']} GB) with ollama pull",
+                          "consent": True})
     else:
         if not os.path.exists(os.path.join(KEY_DIR, "openrouter.key")):
             needs.append({"field": "api_key", "label": "OpenRouter API key",
@@ -427,15 +437,22 @@ def _slug(s):
     return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-")[:40] or "task"
 
 
-def suggestions(a):
+def suggestions(a, f=None):
     """Skills and MCP servers worth adding, from recurring work (actual transcripts).
 
-    Scans every prompt and shell command, so it's cached on the warehouse (reset by sync);
-    installed-state is re-checked on every call.
+    Only Claude Code's own prompts and commands count (these are Claude Code skills and
+    MCP servers; another agent's templated prompts would suggest things Claude never
+    repeats), within the date range when one is given. Scanning is cached per range on
+    the warehouse (reset by sync); installed-state is re-checked on every call.
     """
-    if getattr(a, "_suggest", None) is None:
-        a._suggest = _suggestions(a)
-    out = a._suggest
+    f = f or {}
+    key = (f.get("start"), f.get("end"))
+    cache = getattr(a, "_suggest", None)
+    if not isinstance(cache, dict):
+        cache = a._suggest = {}
+    if key not in cache:
+        cache[key] = _suggestions(a, f)
+    out = cache[key]
     installed = _installed_mcp()
     existing = set(os.listdir(SKILLS_DIR)) if os.path.isdir(SKILLS_DIR) else set()
     for m in out["mcp"]:
@@ -445,13 +462,21 @@ def suggestions(a):
     return out
 
 
-def _suggestions(a):
+def _suggestions(a, f=None):
+    f = f or {}
+    rng, p = "", []
+    if f.get("start"):
+        rng += " AND {t}.day >= ?"; p.append(f["start"])
+    if f.get("end"):
+        rng += " AND {t}.day <= ?"; p.append(f["end"])
     used_tools = {r["name"] for r in a.q("SELECT DISTINCT name FROM tool_calls WHERE name LIKE 'mcp__%'")}
     installed = _installed_mcp()
-    corpus = a.q("""SELECT p.session_id, p.text, p.source, pj.name project FROM prompts p
-                    JOIN projects pj ON pj.id=p.project_id WHERE p.text IS NOT NULL""")
-    bash = a.q("""SELECT t.session_id, t.target, pj.name project FROM tool_calls t
-                  JOIN projects pj ON pj.id=t.project_id WHERE t.name='Bash'""")
+    corpus = a.q(f"""SELECT p.session_id, p.text, p.source, pj.name project FROM prompts p
+                    JOIN projects pj ON pj.id=p.project_id
+                    WHERE p.text IS NOT NULL AND p.agent='claude' {rng.format(t='p')}""", p)
+    bash = a.q(f"""SELECT t.session_id, t.target, pj.name project FROM tool_calls t
+                  JOIN projects pj ON pj.id=t.project_id
+                  WHERE t.name='Bash' AND t.agent='claude' {rng.format(t='t')}""", p)
 
     mcps = []
     for mid, name, what, rx, args, need in MCP_CATALOG:
@@ -527,8 +552,8 @@ def _suggestions(a):
                        "sessions": len(o["sessions"]), "runs": len(o["sessions"]),
                        "projects": sorted(o["projects"], key=o["projects"].get, reverse=True)[:3],
                        "examples": o["examples"], "installed": name in existing,
-                       "what": f"You started {len(o['sessions'])} sessions with \"{k}…\". Save it "
-                               f"as a skill and trigger it with /{name}."})
+                       "what": f"You typed prompts starting \"{k}…\" in {len(o['sessions'])} sessions. "
+                               f"Save it as a skill and trigger it with /{name}."})
     skills.sort(key=lambda x: (x["installed"], -x["sessions"]))
     return {"mcp": mcps[:12], "skills": skills[:15], "skills_dir": SKILLS_DIR,
             "note": "Suggestions come from keywords in your prompts and the shell commands Claude "
@@ -623,7 +648,7 @@ def free_model_test(log, mid):
     return {"ok": True, "command": m["command"]}
 
 
-def compare(a, agents=None):
+def compare(a, agents=None, f=None):
     """Each selected agent's priced models (with your usage) side by side; free models too
     when Claude Code is selected, since they plug into Claude Code."""
     with open(os.path.join(ROOT, "config", "model_compare.json")) as fh:
@@ -632,18 +657,20 @@ def compare(a, agents=None):
     prov = {"claude": "anthropic", "codex": "openai", "gemini": "google"}
     want = {prov[x] for x in agents if x in prov}
     where = {"anthropic": "Anthropic cloud", "openai": "OpenAI cloud", "google": "Google cloud"}
-    ph = ",".join("?" * len(agents))
-    used = {r["model"]: r for r in a.q(f"""SELECT model, COUNT(*) requests, SUM(est_cost_usd) cost,
-                                           SUM(billable_tokens) tokens FROM requests
-                                           WHERE agent IN ({ph}) GROUP BY model""", agents)}
+    w, wp = a.where(dict(f or {}, agents=agents))
+    used = {r["model"]: r for r in a.q(f"""SELECT r.model, COUNT(*) requests, SUM(r.est_cost_usd) cost,
+                                           SUM(r.billable_tokens) tokens FROM requests r
+                                           WHERE {w} GROUP BY r.model""", wp)}
     rows = []
     for mid, p in a.pricing.models.items():
         pv = p.get("provider", "anthropic")
         if p.get("tier") in (None, "none", "other") or pv not in want or mid.endswith("[1m]"):
             continue
-        if pv == "anthropic" and mid not in ratings:
-            continue
         u = used.get(mid) or {}
+        # An unrated Claude model still belongs in the table when you used it; unused
+        # unrated ones (old ids kept for pricing history) would only add noise.
+        if pv == "anthropic" and mid not in ratings and not u:
+            continue
         rt = ratings.get(mid) or {"tools": None, "reasoning": None, "multifile": None,
                                   "speed": "—", "best_for": p.get("tier", "").capitalize() + " tier"}
         rows.append({"id": mid, "name": p.get("display_name", mid), "kind": "claude" if pv == "anthropic" else pv,
@@ -666,6 +693,6 @@ def compare(a, agents=None):
     return {"rows": rows, "os": fm["os"], "ram_gb": fm["models"][0]["ram_gb"] if fm["models"] else None,
             "agents": agents,
             "note": "Ratings are judgement, not benchmarks; edit config/model_compare.json. "
-                    "Unrated models show — until you add them there. Tool use matters most: coding "
+                    "Models you used that have no rating show — until you add them there. Tool use matters most: coding "
                     "agents work by calling tools, and weak tool use means loops, broken edits "
                     "and early stops."}

package/finops/agents.py

@@ -17,6 +17,8 @@ import sqlite3
 import sys
 from datetime import datetime, timezone
 
+from . import localtime
+
 HOME = os.path.expanduser("~")
 IS_WIN, IS_MAC = os.name == "nt", sys.platform == "darwin"
 
@@ -44,10 +46,10 @@ AGENTS = {
                "note": "Tokens and model per reply. Cost estimated at Gemini API list prices; "
                        "the free tier costs nothing."},
     "cursor": {"name": "Cursor", "data": "activity",
-               "paths": [os.path.join(HOME, ".cursor", "projects"), _cursor_state_db()],
-               "note": "Prompts and tool calls from agent transcripts; token counts only where "
-                       "the Cursor IDE stored them, with no model. Cursor bills by subscription, "
-                       "so no cost is estimated."},
+               "paths": [_cursor_state_db()],
+               "note": "Cursor IDE chats: prompts, times and token counts as the IDE stored "
+                       "them, with no model. Cursor bills by subscription, so no cost is "
+                       "estimated. Agent transcripts are not read: they have no times or tokens."},
 }
 
 
@@ -61,7 +63,7 @@ def detect():
 
 
 def _day(ts):
-    return (ts or "")[:10]
+    return localtime.day(ts)
 
 
 def _iso_ms(ms):
@@ -71,10 +73,6 @@ def _iso_ms(ms):
         return None
 
 
-def _iso_mtime(path):
-    return datetime.fromtimestamp(os.path.getmtime(path), timezone.utc).isoformat().replace("+00:00", "Z")
-
-
 class AgentLoader:
     """Writes other agents' usage through the Claude Loader's tables and helpers."""
 
@@ -132,7 +130,7 @@ class AgentLoader:
             " cache_write_5m, cache_write_1h, cache_write_tokens, billable_tokens,"
             " context_tokens, est_cost_usd, est_cost_no_cache_usd, tool_call_count,"
             " is_sidechain, agent) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,0,0,0,?,?,?,?,?,0,?)",
-            (sid, pid, prompt_id, ts, _day(ts), t.hour if t else None, model,
+            (sid, pid, prompt_id, ts, _day(ts), localtime.hour(ts), model,
              1 if priced else 0, inp, out, think, cached, inp + out + cached, inp + cached,
              cost, cost - c_part + nc_part, len(tools), agent))
         rpk = cur.lastrowid
@@ -225,35 +223,11 @@ class AgentLoader:
 
     # ---------- Cursor ----------
     def cursor(self):
-        root = os.path.join(HOME, ".cursor", "projects")
-        for fp in sorted(glob.glob(os.path.join(root, "*", "agent-transcripts", "*", "*.jsonl"))):
-            slug = os.path.relpath(fp, root).split(os.sep)[0]
-            # "Users-me-Documents-JIRA" -> best effort real path, else show the slug
-            guess = "/" + slug.replace("-", "/")
-            cwd = guess if os.path.isdir(guess) else None
-            pid = self.project("cursor", cwd, slug.rsplit("-", 1)[-1] or slug)
-            sid = "cursor-" + os.path.splitext(os.path.basename(fp))[0]
-            ts = _iso_mtime(fp)          # transcripts carry no timestamps; use last write
-            self.session("cursor", sid, pid, fp)
-            prompt_id = None
-            with open(fp, encoding="utf-8", errors="replace") as fh:
-                for line in fh:
-                    try:
-                        o = json.loads(line)
-                    except ValueError:
-                        continue
-                    content = (o.get("message") or {}).get("content") or []
-                    if o.get("role") == "user":
-                        text = " ".join(c.get("text", "") for c in content if isinstance(c, dict))
-                        text = text.replace("<user_query>", "").replace("</user_query>", "").strip()
-                        if text:
-                            prompt_id = self.prompt("cursor", sid, pid, ts, text)
-                    elif o.get("role") == "assistant":
-                        tools = [(c.get("name"), (c.get("input") or "")[:300]
-                                  if isinstance(c.get("input"), str) else
-                                  json.dumps(c.get("input"))[:300])
-                                 for c in content if isinstance(c, dict) and c.get("type") == "tool_use"]
-                        self.request("cursor", sid, pid, prompt_id, ts, "cursor", tools=tools)
+        # Cursor's agent transcripts (~/.cursor/projects/*/agent-transcripts) are not
+        # read: they carry no timestamps and no token counts, so every line would have
+        # been dated by the file's last write and counted as a request it never was.
+        # Only the IDE's own store, which records when each message was sent and its
+        # token counts, is loaded.
         self.cursor_ide()
 
     def cursor_ide(self):