claude-finops 0.13.0 → 0.15.0

package/README.md

@@ -204,14 +204,61 @@ billed at another model's rate.
   },
   "budgets": { "monthly_usd": null, "daily_usd": null, "per_project_usd": {} },
   "alert_thresholds_pct": [50, 75, 90, 100],
+  "guard": {                         // per-session token budget + the session guard hook
+    "session_tokens": null,          // billable tokens per Claude Code session; null => off
+    "warn_pct": [75, 80],            // warn (never block) as a session crosses these
+    "after_approval": "step",        // "step": ask again every step_pct; "once": never again
+    "step_pct": 25,
+    "projects": {}                   // {"/abs/path": {"session_tokens": n} | {"off": true}}
+  },
   "waste_rules": { /* thresholds for each detector */ },
   "anomaly":    { /* z-score and ratio triggers */ },
   "scorecard":  { /* the reference points each dimension is graded against */ }
 }
 ```
 
-The **Budgets** view edits limits, budgets and thresholds from the browser and writes
-them back to this file.
+The **Budgets** page has three numbered blocks (① money, ② tokens, ③ one conversation) and an
+Advanced section, folded away, for plan limits and alert thresholds. **How does this work?** (and
+the small **?** on each block) opens a short picture guide; it also opens by itself the first
+time. Values are saved to `~/.claude-finops/settings.local.json`. Each amount suggests values
+from your own last 30 days, accepts shorthand (`20M`, `500k`, `$3,000`), and explains a bad
+value before saving.
+
+**Live warnings** (inside block ③) is the optional session guard hook. Your budgets work
+without it; it only adds the warning and "continue?" prompt inside Claude Code.
+
+**Settings** (sidebar, Setup) stores the optional API keys used by **Billed vs local**, in
+`~/.claude-finops/secrets.local.json` (0600, the same file `--set-key` writes). The page only
+ever gets back whether a key is set, where from, and its last four characters. An environment
+variable (`ANTHROPIC_ADMIN_KEY`, `CURSOR_API_KEY`) takes priority over a stored key.
+
+### Per-session token budget and the session guard
+
+`guard.session_tokens` is a budget for one Claude Code session, in billable tokens (input +
+output + cache read + cache write, the same figure as the Tokens column in Sessions). Cache
+reads dominate long sessions, which is exactly what a session cap is for. A project override
+(matched on the project path; the most specific path wins) sets a different budget or turns
+it off for that project.
+
+With a budget set, **Budgets** shows the largest session this billing period against its
+budget and how many sessions went over, and the dots in **Sessions** mark sessions at 75%
+(amber) and 100% (red) of theirs.
+
+The **session guard** is an opt-in Claude Code `PreToolUse` hook (`--install-guard`, or
+**Install** under Live warnings on the Budgets page, block ③). Before each tool call it counts the session's tokens
+from its transcript (only the lines added since the last call), and:
+
+- below the budget, warns you once at each `warn_pct` and suggests `/compact` to Claude;
+- at 100%, asks you to approve the next tool call; after you approve, it asks again every
+  `step_pct` (`"step"`) or not at all for that session (`"once"`). If you decline, it asks
+  again on the next tool call.
+
+Checked on Claude Code 2.1.284: the approval prompt appears in the default mode, in
+`--dangerously-skip-permissions` (bypass) mode, and for tools on your allow list. In
+non-interactive `claude -p` there is nobody to ask, so the tool call is refused. A hook cannot
+end a session, and the guard fails open: if it errors or cannot read the transcript, the tool
+call goes ahead. It keeps a small state file per session in `~/.claude-finops/data/guard/`
+(deleted after 30 days).
 
 Note on `waste_rules.low_output_ratio_vs_median`: sessions are flagged relative to
 *your own* median output ratio rather than an absolute number, because a healthy ratio
@@ -277,6 +324,8 @@ claude-finops --set-key       store a provider API key (hidden prompt, 0600)
 claude-finops --keys          which provider keys are configured
 claude-finops --install-statusline    model, context % and 5-hour limit under every prompt
 claude-finops --uninstall-statusline  remove it again
+claude-finops --install-guard         warn near, and ask at, your per-session token budget
+claude-finops --uninstall-guard       remove it again
 claude-finops --help          everything
 ```
 
@@ -298,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/`
@@ -328,7 +391,8 @@ The app makes exactly one outbound request of its own: once a day it asks
 you when an upgrade is out (npm has no way to push one at you). It sends nothing
 about you or your usage. Turn it off with `NO_UPDATE_NOTIFIER=1` or
 `CLAUDE_FINOPS_NO_UPDATE_CHECK=1`. Provider cost APIs are called only if you
-configure a key with `--set-key`.
+configure a key (with `--set-key` or on the Settings page), and only
+when you click Refresh on Billed vs local.
 
 ---
 
@@ -390,6 +454,53 @@ files on Windows.
 - **Install statusline** (Act now, or `--install-statusline`) adds a `statusLine` entry to
   `~/.claude/settings.json`, keeping a `.finops-backup` copy. It won't replace a statusline you
   already have.
+- **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.
+
+---
+
+## Jev (fast decisions)
+
+[Jev](https://docs.typesafe.ai) is TypeSafe AI's "System One" model: very fast, very cheap typed
+decisions (pick one, yes or no, a score, a value). It does not write text or code, so it does not
+make Claude Code itself cheaper; it makes the apps and scripts you build cheaper where an LLM call
+only decides something.
+
+The **Jev (fast decisions)** page (sidebar, Optimize):
+
+- **Install** runs Claude Code's own plugin manager, after showing you the commands:
+  `claude plugin marketplace add typesafe-ai/skills` then `claude plugin install typesafe@typesafe-ai`.
+  **Uninstall** runs `claude plugin uninstall typesafe@typesafe-ai`.
+- **API key** is saved as `env.TYPESAFE_API_KEY` in `~/.claude/settings.json` (backed up first,
+  nothing else changed), so new Claude Code sessions can use it. The page only ever gets back
+  its last four characters. A key exported in your shell takes priority.
+- **Where Jev fits** counts your Claude Code prompts that were really just a decision (short, no
+  tools, worded as "which one", "yes or no", "classify"…) and what they would cost at TypeSafe's
+  published price ($0.042 per million input tokens). Read-only.
 
 ---
 
@@ -401,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

@@ -30,6 +30,23 @@
     90,
     100
   ],
+  "guard": {
+    "_comment": "Per-session token budget (billable tokens) and the opt-in session guard hook (claude-finops --install-guard). session_tokens null => no per-session budget and the guard allows everything. projects maps an absolute project path to {\"session_tokens\": n} or {\"off\": true}; sessions maps one Claude Code session id to the same (set from Running sessions, forgotten after 30 days).",
+    "session_tokens": null,
+    "warn_pct": [75, 80],
+    "after_approval": "step",
+    "step_pct": 25,
+    "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):