claude-finops 0.4.4 → 0.6.0

package/README.md

@@ -287,6 +287,28 @@ place for you to delete once you are happy.
 
 ---
 
+## 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/finops/advisor.py

@@ -0,0 +1,188 @@
+"""Live model advice: what to switch to, while the session is still running.
+
+The back-test in analytics.model_evidence() answers "what should I have used?",
+which is the wrong tense once a session is under way. This module answers it in
+the present: given the prompts a session has actually sent and the model it is
+on, say whether your own history already shows a cheaper model doing this kind
+of work without taking more turns.
+
+It is built to run three ways, so the advice is the same wherever you meet it:
+
+  * the dashboard's Running sessions view (per live session)
+  * a UserPromptSubmit hook (per prompt, before the turn runs)
+  * a statusline command (continuously, in a few characters)
+
+The hook and statusline run on every prompt, so the evidence is computed once
+and cached; a warehouse query per keystroke would be felt. Everything here fails
+soft and silent — advice that breaks your terminal is worse than no advice.
+"""
+import json
+import os
+import time
+
+from .classify import classify
+from .paths import DATA_DIR, DB_PATH, ensure_dirs
+
+CACHE = os.path.join(DATA_DIR, "advice_cache.json")
+TTL_S = 3600
+RECENT_PROMPTS = 12      # how much of the session counts as "what it is doing now"
+MIN_SAVING_PCT = 25      # below this, interrupting someone is not worth it
+
+# `/model <name>` takes a family name, not the pricing table's id.
+ALIASES = ("opus", "sonnet", "haiku", "fable")
+
+
+def model_alias(model_id):
+    """'claude-fable-5-1' -> 'fable'. Falls back to the full id we were given."""
+    low = str(model_id or "").lower()
+    for a in ALIASES:
+        if a in low:
+            return a
+    return model_id
+
+
+# ---------------------------------------------------------------- evidence ----
+
+def _build_evidence():
+    """Pull the back-test into the small shape the live surfaces need."""
+    from .analytics import Analytics
+    a = Analytics(DB_PATH)
+    ev = a.model_evidence({})
+    out = {}
+    for c in ev["categories"]:
+        cands = [{"model": x["model"], "name": x["name"], "verdict": x["verdict"],
+                  "cost_per_prompt": round(x["cost_per_prompt"], 3),
+                  "savings_pct": x["savings_pct"], "turn_ratio": x["turn_ratio"],
+                  "prompts": x["prompts"], "why": x["why"]}
+                 for x in c["candidates"]]
+        out[c["category"]] = {"current": c["current"]["model"],
+                              "current_name": c["current"]["name"],
+                              "current_cost_per_prompt": round(c["current"]["cost_per_prompt"], 3),
+                              "agent": c.get("agent", "claude"),
+                              "candidates": cands}
+    return out
+
+
+def evidence(force=False):
+    """Cached evidence table, keyed by category. Never raises."""
+    try:
+        with open(CACHE) as fh:
+            c = json.load(fh)
+        if not force and time.time() - c.get("built_at", 0) < TTL_S:
+            return c.get("categories") or {}
+    except (OSError, ValueError):
+        pass
+    try:
+        cats = _build_evidence()
+    except Exception:
+        return {}
+    try:
+        ensure_dirs()
+        tmp = CACHE + ".tmp"
+        with open(tmp, "w") as fh:
+            json.dump({"built_at": int(time.time()), "categories": cats}, fh)
+        os.replace(tmp, CACHE)
+    except OSError:
+        pass
+    return cats
+
+
+# ---------------------------------------------------------------- session ----
+
+def recent_prompts(transcript, n=RECENT_PROMPTS):
+    """The last n human prompts in a live transcript, newest last.
+
+    Reads the tail only: an active session's JSONL runs to tens of megabytes and
+    this is on the path of every prompt you type.
+    """
+    try:
+        size = os.path.getsize(transcript)
+        with open(transcript, "rb") as fh:
+            fh.seek(max(0, size - 400_000))
+            lines = fh.read().decode("utf-8", "replace").splitlines()[1:]
+    except OSError:
+        return []
+    out = []
+    for line in reversed(lines):
+        if '"type":"user"' not in line and '"type": "user"' not in line:
+            continue
+        try:
+            d = json.loads(line)
+        except ValueError:
+            continue
+        if d.get("isMeta") or d.get("isSidechain"):
+            continue
+        msg = d.get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, list):
+            content = " ".join(b.get("text", "") for b in content
+                               if isinstance(b, dict) and b.get("type") == "text")
+        if not isinstance(content, str) or not content.strip():
+            continue
+        if content.lstrip().startswith(("<", "[Request interrupted")):
+            continue          # tool results and interrupt markers are not prompts
+        out.append(content)
+        if len(out) >= n:
+            break
+    return list(reversed(out))
+
+
+def category_of(texts):
+    """The category this stretch of work is in, by weight of confidence."""
+    scores = {}
+    for t in texts:
+        cat, conf, _ = classify(t)
+        scores[cat] = scores.get(cat, 0) + max(conf, 0.1)
+    if not scores:
+        return "other", 0.0
+    cat = max(scores, key=scores.get)
+    return cat, round(scores[cat] / sum(scores.values()), 2)
+
+
+def advise(model=None, transcript=None, prompt=None, ev=None):
+    """What to say about a session that is running right now.
+
+    model      the model the session is on (pricing-table id)
+    transcript path to the live JSONL, for reading what it has been doing
+    prompt     the prompt about to be sent, when we are called from a hook
+    Returns None when there is nothing worth saying.
+    """
+    ev = evidence() if ev is None else ev
+    if not ev:
+        return None
+    texts = list(recent_prompts(transcript)) if transcript else []
+    if prompt:
+        # The prompt in hand is what the next turn will cost, so it leads.
+        texts = texts[-4:] + [prompt] * 3
+    if not texts:
+        return None
+    cat, conf = category_of(texts)
+    row = ev.get(cat)
+    if not row:
+        return None
+    # Only speak when they are on the model the evidence is about. Advising a
+    # switch away from a model you already left would be noise.
+    if model and row["current"] and model_alias(model) != model_alias(row["current"]):
+        return None
+    usable = [c for c in row["candidates"]
+              if c["verdict"] in ("supported", "caution") and c["savings_pct"] >= MIN_SAVING_PCT]
+    if not usable:
+        return None
+    best = usable[0]
+    trial = best["verdict"] == "caution"
+    return {
+        "category": cat, "confidence": conf,
+        "current_model": row["current"], "current_name": row["current_name"],
+        "current_cost_per_prompt": row["current_cost_per_prompt"],
+        "model": best["model"], "name": best["name"], "alias": model_alias(best["model"]),
+        "cost_per_prompt": best["cost_per_prompt"], "savings_pct": best["savings_pct"],
+        "turn_ratio": best["turn_ratio"], "prompts": best["prompts"],
+        "verdict": best["verdict"], "trial": trial, "why": best["why"],
+        "command": f"/model {model_alias(best['model'])}",
+        "line": (f"{cat.replace('_', ' ')} on {row['current_name']} "
+                 f"(${row['current_cost_per_prompt']:.2f}/prompt). Your last {best['prompts']} "
+                 f"ran on {best['name']} at ${best['cost_per_prompt']:.2f} in "
+                 f"{best['turn_ratio']}x the turns"
+                 + (" — worth a trial here." if trial else ".")),
+        "short": f"try {model_alias(best['model'])} (-{best['savings_pct']:.0f}%)",
+    }

package/finops/analytics.py

@@ -886,6 +886,155 @@ class Analytics:
               and (provider is None or v.get("provider", "anthropic") == provider)]
         return min(ms, key=lambda m: self.pricing.rates(m).get("output", 1e9)) if ms else None
 
+    # ---------------- evidence: what the cheaper model actually did ----------------
+    # model_switch() reprices your tokens on a cheaper model, which assumes the cheaper
+    # model would have done the same work in the same number of turns. Often it would
+    # not: a weaker model can take five times the turns on the same task, and the
+    # repricing then promises a saving that never arrives.
+    #
+    # Where you have already run more than one model on the same kind of work, we do not
+    # have to assume anything. This compares what each model actually cost per prompt on
+    # that category, and how much work it took to get there.
+
+    MIN_PROMPTS = 8          # below this a per-category average is noise, not evidence
+    SAVING_FLOOR_PCT = 20    # smaller gaps are inside the noise of what you happened to ask
+    TURN_TOLERANCE = 1.35    # more turns than this and the cheaper model was grinding
+    REPEAT_TOLERANCE = 12.0  # percentage points of extra re-asking we will accept
+
+    def model_evidence(self, f=None):
+        """Back-test a model switch against your own history.
+
+        For every category where you ran more than one model, report what each one
+        actually cost per prompt and what it took: turns, tool calls, and how often you
+        had to ask the same thing again. A candidate is only recommended when it was
+        genuinely cheaper per prompt *and* did not need materially more work to get
+        there — which is the part a repricing cannot see.
+        """
+        w, p = self.where(f)
+        # The filter is request-scoped, so select the prompts it touches as a subquery.
+        # Joining requests directly would repeat each prompt once per request and quietly
+        # multiply both the counts and every average by the turn count.
+        scope = f"pr.id IN (SELECT r.prompt_id FROM requests r WHERE {w})"
+        # Single-model prompts only: a prompt answered by two models cannot be
+        # attributed to either, and mixed rows would blur the comparison.
+        clean = ("pr.models IS NOT NULL AND pr.models NOT LIKE '%,%' "
+                 "AND pr.models != '<synthetic>' AND pr.est_cost_usd > 0")
+        rows = self.q(f"""SELECT COALESCE(pr.category,'other') category, pr.models model,
+            pr.agent agent, COUNT(*) prompts, SUM(pr.est_cost_usd) cost,
+            AVG(pr.est_cost_usd) cost_per_prompt,
+            AVG(pr.request_count) turns, AVG(pr.tool_calls) tools,
+            AVG(pr.output_tokens) out_tokens, AVG(pr.max_context_tokens) ctx
+            FROM prompts pr WHERE {scope} AND {clean}
+            GROUP BY 1, 2, 3 HAVING prompts >= ?""", p + [self.MIN_PROMPTS])
+
+        repeats = {(r["category"], r["model"]): r["pct"] for r in self.q(f"""
+            SELECT COALESCE(pr.category,'other') category, pr.models model,
+                ROUND(100.0 * SUM(CASE WHEN dup.n > 1 THEN 1 ELSE 0 END) / COUNT(*), 1) pct
+            FROM prompts pr
+            LEFT JOIN (SELECT norm_hash, COUNT(*) n FROM prompts GROUP BY norm_hash) dup
+                   ON dup.norm_hash = pr.norm_hash
+            WHERE {scope} AND {clean}
+            GROUP BY 1, 2""", p)}
+
+        by_cat = defaultdict(list)
+        for r in rows:
+            r["repeat_pct"] = repeats.get((r["category"], r["model"]), 0.0) or 0.0
+            r["name"] = self.pricing.display_name(r["model"])
+            r["tier"] = self.pricing.tier(r["model"])
+            by_cat[r["category"]].append(r)
+
+        out, total_save = [], 0.0
+        for cat, models in by_cat.items():
+            if len(models) < 2:
+                continue
+            # The incumbent is what you spend the most on here — that is the bill a
+            # switch would actually change.
+            cur = max(models, key=lambda m: m["cost"])
+            rule = self.SWITCH_RULES.get(cat, ("balanced", "low"))[0]
+            cands = []
+            for m in models:
+                if m["model"] == cur["model"] or m["cost_per_prompt"] >= cur["cost_per_prompt"]:
+                    continue
+                # Only models the same agent can run. Telling a Claude Code user to use a
+                # GPT model is not a setting change, it is a different tool, and the
+                # comparison would be between two different ways of working.
+                if m["agent"] != cur["agent"]:
+                    continue
+                save_pct = 100.0 * (1 - m["cost_per_prompt"] / cur["cost_per_prompt"])
+                turn_ratio = (m["turns"] / cur["turns"]) if cur["turns"] else 1.0
+                repeat_delta = m["repeat_pct"] - cur["repeat_pct"]
+                # Observed, not repriced: what your own prompts cost on each side.
+                save = (cur["cost_per_prompt"] - m["cost_per_prompt"]) * cur["prompts"]
+                if save_pct < self.SAVING_FLOOR_PCT:
+                    verdict, why = "marginal", (
+                        f"Only {save_pct:.0f}% cheaper per prompt — inside the noise of what "
+                        f"you happened to ask each model.")
+                elif turn_ratio > self.TURN_TOLERANCE:
+                    verdict, why = "risky", (
+                        f"Cost {save_pct:.0f}% less per prompt but took {turn_ratio:.1f}x the "
+                        f"turns ({m['turns']:.0f} vs {cur['turns']:.0f}). It got there by "
+                        f"grinding, and that is the cost the headline number misses.")
+                elif repeat_delta > self.REPEAT_TOLERANCE:
+                    verdict, why = "risky", (
+                        f"{save_pct:.0f}% cheaper per prompt, but you re-asked "
+                        f"{m['repeat_pct']:.0f}% of these prompts against "
+                        f"{cur['repeat_pct']:.0f}% on {cur['name']} — rework you paid for twice.")
+                elif rule == "keep":
+                    verdict, why = "caution", (
+                        f"{save_pct:.0f}% cheaper per prompt and no more turns, but {cat.replace('_',' ')} "
+                        f"is reasoning-heavy work where a miss is expensive in ways this data "
+                        f"cannot show. Worth a trial, not a default.")
+                else:
+                    verdict, why = "supported", (
+                        f"{save_pct:.0f}% cheaper per prompt on {m['prompts']} of your own "
+                        f"{cat.replace('_',' ')} prompts, in {turn_ratio:.1f}x the turns "
+                        f"({m['turns']:.0f} vs {cur['turns']:.0f}) with "
+                        f"{'less' if repeat_delta <= 0 else 'similar'} re-asking. "
+                        f"This is measured, not modelled.")
+                cands.append({
+                    "model": m["model"], "name": m["name"], "tier": m["tier"],
+                    "prompts": m["prompts"], "cost_per_prompt": m["cost_per_prompt"],
+                    "turns": m["turns"], "tools": m["tools"], "repeat_pct": m["repeat_pct"],
+                    "savings_pct": round(save_pct, 1), "turn_ratio": round(turn_ratio, 2),
+                    "repeat_delta": round(repeat_delta, 1),
+                    "estimated_savings_usd": round(save, 2), "verdict": verdict, "why": why})
+            if not cands:
+                continue
+            cands.sort(key=lambda c: (c["verdict"] != "supported", -c["estimated_savings_usd"]))
+            best = cands[0] if cands[0]["verdict"] == "supported" else None
+            if best:
+                total_save += best["estimated_savings_usd"]
+            out.append({
+                "category": cat,
+                "agent": cur["agent"],
+                "current": {"model": cur["model"], "name": cur["name"], "prompts": cur["prompts"],
+                            "cost": cur["cost"], "cost_per_prompt": cur["cost_per_prompt"],
+                            "turns": cur["turns"], "tools": cur["tools"],
+                            "repeat_pct": cur["repeat_pct"]},
+                "candidates": cands,
+                "recommended": best["model"] if best else None,
+                "recommended_name": best["name"] if best else None,
+                "estimated_savings_usd": best["estimated_savings_usd"] if best else 0.0,
+                "verdict": best["verdict"] if best else cands[0]["verdict"],
+                "why": best["why"] if best else cands[0]["why"],
+                "rule": rule,
+            })
+        out.sort(key=lambda c: -c["estimated_savings_usd"])
+        return {
+            "categories": out,
+            "estimated_savings_usd": round(total_save, 2),
+            "min_prompts": self.MIN_PROMPTS,
+            "basis": "actual",
+            "method": (f"Compares what each model actually cost per prompt on the same category "
+                       f"of work, using only categories where you ran both with at least "
+                       f"{self.MIN_PROMPTS} prompts each. Turns and re-asked prompts are shown "
+                       f"because a cheaper model that needs more of both is not cheaper. "
+                       f"Nothing here is repriced or modelled."),
+            "caveat": ("Your prompts were not randomly assigned to models, so a category can "
+                       "differ in difficulty between them. Treat this as strong evidence for a "
+                       "trial, not proof."),
+        }
+
     def model_switch(self, f=None):
         """Per-request what-if: reprice each request on the model its work needs.
 

package/finops/api.py

@@ -292,6 +292,8 @@ class Handler(BaseHTTPRequestHandler):
             return self.send_json(a.context_analysis(f))
         if route == "waste":
             return self.send_json(a.waste(f))
+        if route == "model_evidence":
+            return self.send_json(a.model_evidence(f))
         if route == "model_switch":
             return self.send_json(a.model_switch(f))
         if route == "recommendations":
@@ -321,6 +323,17 @@ class Handler(BaseHTTPRequestHandler):
             others = list_agent_sessions(a.pricing, [x for x in want if x != "claude"] or None) \
                 if not want or any(x != "claude" for x in want) else []
             rows = sorted(claude + others, key=lambda x: -(x.get("context") or 0))
+            # Live model advice, while the session can still act on it. One cached
+            # evidence read for the whole list, and never fatal to the view.
+            try:
+                from .advisor import advise, evidence
+                ev = evidence()
+                for r in rows:
+                    r["advice"] = advise(model=r.get("model"), transcript=r.get("transcript"),
+                                         ev=ev) if ev else None
+            except Exception:
+                for r in rows:
+                    r.setdefault("advice", None)
             return self.send_json({"sessions": rows})
         if route == "cloud":
             from .cloud import report

package/finops/integrate.py

@@ -0,0 +1,168 @@
+"""Live advice inside Claude Code itself: a prompt hook and a statusline.
+
+The dashboard can only advise you if you are looking at it. These two run where
+the decision is actually made — the terminal you are typing in.
+
+  claude-finops --hook          reads a UserPromptSubmit payload on stdin
+  claude-finops --statusline    reads a statusline payload on stdin
+  claude-finops --install-hook / --install-statusline   wire them into settings
+
+Both are on the path of every prompt, so both are built to be boring: fail
+silent, never block, never take long. A hook that erases someone's prompt
+because a database was locked is a far worse bug than missing advice, so the
+hook never returns a blocking exit code — it exits 0 whatever happens.
+"""
+import json
+import os
+import shutil
+import sys
+
+SETTINGS = os.path.join(os.path.expanduser("~"), ".claude", "settings.json")
+
+
+def _stdin_json():
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except (ValueError, OSError):
+        return {}
+
+
+def _dig(d, *paths, default=None):
+    """First present value among dotted paths.
+
+    The payload shapes are not identical across Claude Code versions, and a
+    statusline that breaks on upgrade is worse than one that misses a field, so
+    every read tries the spellings we know of.
+    """
+    for path in paths:
+        cur = d
+        for part in path.split("."):
+            if not isinstance(cur, dict) or part not in cur:
+                cur = None
+                break
+            cur = cur[part]
+        if cur not in (None, ""):
+            return cur
+    return default
+
+
+def _payload_common(d):
+    return (_dig(d, "model", "session.model", "model.id", "model.display_name"),
+            _dig(d, "transcript_path", "session.transcript_path", "transcriptPath"))
+
+
+# -------------------------------------------------------------------- hook ----
+
+def hook():
+    """UserPromptSubmit: judge the prompt in hand, before it is paid for.
+
+    Advice goes to the user as `systemMessage`, not into Claude's context: it is
+    for the person deciding which model to use, and feeding it to the model
+    would just spend tokens telling it about its own price.
+    """
+    try:
+        d = _stdin_json()
+        prompt = _dig(d, "user_prompt", "prompt", default="")
+        model, transcript = _payload_common(d)
+        from .advisor import advise
+        a = advise(model=model, transcript=transcript, prompt=prompt)
+        if a:
+            print(json.dumps({"systemMessage": f"finops: {a['line']}  →  {a['command']}"}))
+    except Exception:
+        pass          # never let advice interfere with the prompt
+    return 0
+
+
+# -------------------------------------------------------------- statusline ----
+
+def statusline():
+    """One line, refreshed constantly, so: what you are on, and what to try."""
+    try:
+        d = _stdin_json()
+        model, transcript = _payload_common(d)
+        pct = _dig(d, "context.percentUsed", "context.percent_used")
+        name = _dig(d, "model.display_name", "session.model", "model") or "claude"
+        bits = [str(name)]
+        if isinstance(pct, (int, float)):
+            bits.append(f"{pct:.0f}% ctx")
+        from .advisor import advise
+        a = advise(model=model, transcript=transcript)
+        if a:
+            bits.append(a["short"])
+        print(" · ".join(bits))
+    except Exception:
+        print("")     # an empty statusline beats a stack trace under the prompt
+    return 0
+
+
+# --------------------------------------------------------------- installing ----
+
+def _command():
+    """How to invoke us from settings: the installed CLI if it is on PATH."""
+    exe = shutil.which("claude-finops")
+    if exe:
+        return exe
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    return f"{sys.executable} {os.path.join(root, 'run.py')}"
+
+
+def _load_settings():
+    try:
+        with open(SETTINGS) as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_settings(data):
+    os.makedirs(os.path.dirname(SETTINGS), exist_ok=True)
+    if os.path.exists(SETTINGS):
+        # Their settings file is not ours to lose.
+        shutil.copy2(SETTINGS, SETTINGS + ".finops-backup")
+    with open(SETTINGS, "w") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+
+
+def install_hook(remove=False):
+    cmd = f"{_command()} --hook"
+    s = _load_settings()
+    hooks = s.setdefault("hooks", {}).setdefault("UserPromptSubmit", [])
+    for group in hooks:                       # drop any earlier copy of ours
+        group["hooks"] = [h for h in group.get("hooks", [])
+                          if "--hook" not in str(h.get("command", ""))
+                          or "finops" not in str(h.get("command", ""))]
+    hooks[:] = [g for g in hooks if g.get("hooks")]
+    if not remove:
+        hooks.append({"matcher": "", "hooks": [{"type": "command", "command": cmd,
+                                                "timeout": 10}]})
+    if not hooks:
+        s["hooks"].pop("UserPromptSubmit", None)
+        if not s["hooks"]:
+            s.pop("hooks")
+    _save_settings(s)
+    print(("Removed" if remove else "Installed") + f" the prompt hook in {SETTINGS}")
+    if not remove:
+        print("  It suggests a cheaper model when your own history backs one, before the turn runs.")
+        print("  Start a new Claude Code session to pick it up.  Undo: claude-finops --uninstall-hook")
+
+
+def install_statusline(remove=False):
+    cmd = f"{_command()} --statusline"
+    s = _load_settings()
+    if remove:
+        if "finops" in str(s.get("statusLine", "")):
+            s.pop("statusLine", None)
+    else:
+        prev = s.get("statusLine")
+        if prev and "finops" not in str(prev):
+            print(f"You already have a statusLine configured:\n  {prev}")
+            print("Leaving it alone. Remove it first if you want ours.")
+            return
+        s["statusLine"] = cmd
+    _save_settings(s)
+    print(("Removed" if remove else "Installed") + f" the statusline in {SETTINGS}")
+    if not remove:
+        print("  Shows the model, context pressure, and a cheaper model when one is warranted.")
+        print("  Undo: claude-finops --uninstall-statusline")

package/finops/procs.py

@@ -85,6 +85,7 @@ def _transcript_stats(session_id, pricing):
     steps = tokens = 0
     ctx = None
     cost = 0.0
+    model = None          # the model of the most recent assistant turn: what you are on now
     with open(fp, errors="replace") as fh:
         for line in fh:
             if '"usage"' not in line:
@@ -108,7 +109,8 @@ def _transcript_stats(session_id, pricing):
             if not (c5 or c1):
                 c5 = cw
             cost += pricing.estimate(m.get("model"), inp, out, cr, c5, c1)
-    return {"transcript": fp, "steps": steps, "tokens": tokens, "context": ctx,
+            model = m.get("model") or model
+    return {"transcript": fp, "steps": steps, "tokens": tokens, "context": ctx, "model": model,
             "est_cost_usd": cost, "last_write_s": time.time() - os.path.getmtime(fp)}
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-finops",
-  "version": "0.4.4",
+  "version": "0.6.0",
   "description": "Local FinOps dashboard for Claude Code: what you used, what it cost, why it cost that much, and what to change. Reads your own transcripts, no API key, no data leaves the machine.",
   "bin": {
     "claude-finops": "bin/claude-finops.js"

package/run.py

@@ -171,6 +171,9 @@ HELP = """Claude FinOps Command Center
   claude-finops --keys          list which provider keys are configured
   claude-finops --share         write ../claude-finops.zip (code only, never your data)
   claude-finops --version       print the installed version, and whether a newer one is out
+  claude-finops --advise        what to switch to in the sessions running right now
+  claude-finops --install-hook  suggest a cheaper model in Claude Code, as you send each prompt
+  claude-finops --install-statusline   show model, context and advice in your statusline
   claude-finops --help          this message
 
 Environment:
@@ -182,6 +185,28 @@ Environment:
 """
 
 
+def advise_now():
+    """What every session running right now should consider switching to."""
+    from finops.advisor import advise, evidence
+    from finops.procs import list_sessions
+    from finops.analytics import Analytics
+    ev = evidence()
+    if not ev:
+        return print("No model evidence yet — you need two models run on the same kind of "
+                     "work before there is anything to compare.")
+    rows = list_sessions(Analytics(DB_PATH).pricing)
+    if not rows:
+        return print("No Claude Code sessions are running.")
+    for r in rows:
+        a = advise(model=r.get("model"), transcript=r.get("transcript"), ev=ev)
+        head = f"  {r.get('project') or r.get('session_id') or 'session'}"
+        if a:
+            print(f"{head}: {a['line']}")
+            print(f"{' ' * len(head)}  run {a['command']}")
+        else:
+            print(f"{head}: nothing to change.")
+
+
 def _version():
     from finops.update import _installed
     return _installed()
@@ -292,6 +317,23 @@ def main():
         return print(HELP)
     if "--version" in args or "-v" in args or "-V" in args:
         return version()
+    # Integration entry points. --hook and --statusline are invoked by Claude Code
+    # with a JSON payload on stdin, many times a session; they print one line and
+    # never fail loudly.
+    if "--hook" in args:
+        from finops.integrate import hook
+        return sys.exit(hook())
+    if "--statusline" in args:
+        from finops.integrate import statusline
+        return sys.exit(statusline())
+    if "--install-hook" in args or "--uninstall-hook" in args:
+        from finops.integrate import install_hook
+        return install_hook(remove="--uninstall-hook" in args)
+    if "--install-statusline" in args or "--uninstall-statusline" in args:
+        from finops.integrate import install_statusline
+        return install_statusline(remove="--uninstall-statusline" in args)
+    if "--advise" in args:
+        return advise_now()
     if "--where" in args:
         return where()
     if "--keys" in args:

package/web/app.js

@@ -1322,12 +1322,53 @@ VIEWS.context = async (page) => {
 };
 
 /* ---------- model switch ---------- */
+// Verdicts from the back-test. Wording matters here: "supported" means your own
+// history backs the switch, not that we modelled it.
+const VERDICT = {
+  supported: ['🟢', 'Backed by your data', 'healthy'],
+  caution:   ['🟠', 'Trial first', 'approaching'],
+  risky:     ['🔴', 'Cost more work', 'critical'],
+  marginal:  ['⚪', 'Too close to call', 'high'],
+};
+
+function evidenceBody(ev) {
+  if (!ev || !ev.categories?.length) {
+    return `<div class="empty">No category yet has ${ev?.min_prompts || 8}+ prompts on two
+      different models of the same agent, so there is nothing to compare. Run a cheaper model on
+      a handful of real tasks and this fills in.</div>`;
+  }
+  const rows = [];
+  ev.categories.forEach(c => c.candidates.forEach((x, i) => rows.push({c, x, first: i === 0})));
+  return table([
+    {h: 'Work', f: r => r.first ? `<b>${esc(r.c.category.replace('_', ' '))}</b>` : ''},
+    {h: 'You use now', f: r => r.first
+      ? `${esc(r.c.current.name)} <span class="note">${fmtUSD(r.c.current.cost_per_prompt)}/prompt ·
+         ${Math.round(r.c.current.turns)} turns</span>` : ''},
+    {h: 'Instead of', f: r => `<b>${esc(r.x.name)}</b>`},
+    {h: '$ / prompt', num: 1, f: r => fmtUSD(r.x.cost_per_prompt)},
+    {h: 'Turns', num: 1, f: r => `${Math.round(r.x.turns)} <span class="note">(${r.x.turn_ratio}×)</span>`},
+    {h: 'Re-asked', num: 1, f: r => `${fmtPct(r.x.repeat_pct)}<span class="note">${
+      r.x.repeat_delta > 0 ? ' +' + r.x.repeat_delta : ''}</span>`},
+    {h: 'On', num: 1, f: r => `${fmtInt(r.x.prompts)} prompts`},
+    {h: 'Verdict', f: r => `<span title="${esc(r.x.why)}">${
+      statusChip(VERDICT[r.x.verdict][2], VERDICT[r.x.verdict][1])}</span>`},
+    {h: 'Would save', num: 1, f: r => r.x.verdict === 'supported'
+      ? `<b>${fmtUSD(r.x.estimated_savings_usd)}</b>` : `<span class="note">${fmtUSD(r.x.estimated_savings_usd)}</span>`},
+  ], rows) + `<div class="note" style="padding:10px 14px">${esc(ev.method)}</div>`;
+}
+
 VIEWS.modelswitch = async (page) => {
-  const m = await api('model_switch');
+  const [m, ev] = await Promise.all([
+    api('model_switch'),
+    api('model_evidence').catch(() => null),
+  ]);
   const sc = m.savings_by_confidence || {};
   const conf = c => `<span class="badge rec">${esc(c)} confidence</span>`;
   page.innerHTML = `
     <div class="grid g4">
+      ${kpi('Backed by your own runs', fmtUSD(ev?.estimated_savings_usd || 0),
+        `${ev?.categories?.filter(c => c.recommended).length || 0} categories where a cheaper model
+         already did the same work for less`, {badge: BADGE.actual})}
       ${kpi('Potential savings', fmtUSD(m.estimated_savings_usd),
         `${fmtPct(m.total_cost_usd ? 100 * m.estimated_savings_usd / m.total_cost_usd : 0)} of ${fmtUSD(m.total_cost_usd)} in range`,
         {badge: BADGE.recommendation})}
@@ -1336,7 +1377,15 @@ VIEWS.modelswitch = async (page) => {
       ${kpi('Stays on current model', fmtUSD(m.blocked_by_context_usd),
         `${fmtInt(m.blocked_by_context_requests)} requests too big for the cheaper model's context`, {badge: BADGE.estimated})}
     </div>
-    ${card('Switch these', `<div id="ms-sw"></div>`, {badge: BADGE.recommendation, flush: 1,
+    ${card('What actually happened when you used a cheaper model',
+      `<div id="ms-ev">${evidenceBody(ev)}</div>`, {badge: BADGE.actual, flush: 1,
+      hint: 'Measured from your own prompts — no repricing, no assumptions about tokens',
+      footer: ev ? esc(ev.caveat) : ''})}
+    <div class="note">The table above is history; the one below is a model. Where they disagree,
+      believe the history: repricing assumes the cheaper model would finish in the same number of
+      turns, and your data shows that is often where the saving goes.</div>
+    ${card('Switch these (repriced, not measured)', `<div id="ms-sw"></div>`,
+      {badge: BADGE.recommendation, flush: 1,
       hint: 'Each request repriced on the model its work needs, same tokens',
       footer: esc(m.caveat)})}
     ${card('Default model per project', `<div id="ms-pj"></div>`, {badge: BADGE.recommendation, flush: 1,
@@ -1595,6 +1644,10 @@ VIEWS.live = async (page) => {
         <div class="dt">${x.status === 'busy' ? '<b>Working now</b>' : 'Idle'}${x.uptime ? ` · up ${esc(x.uptime)}` : ''} ·
           last activity ${x.last_write_s == null ? '—' : dur(x.last_write_s)} ago${x.memory_mb == null ? '' : ` · ${fmtInt(x.memory_mb)} MB`} ·
           <span class="note">${esc(x.cwd)}</span></div>
+        ${x.advice ? `<div class="dt switch-tip"><b>${x.advice.trial ? 'Worth trying' : 'Cheaper model'}:</b>
+          ${esc(x.advice.line)}
+          <button class="act ghost" data-copy="${esc(x.advice.command)}"
+            title="${esc(x.advice.why)}">Copy ${esc(x.advice.command)}</button></div>` : ''}
         ${x.severity !== 'ok' ? `<div class="dt"><b>Advice:</b> ${x.severity === 'high'
           ? 'Very large context. Use <b>Hand over</b> to continue in a fresh session, or split the remaining work into sub-sessions.'
           : 'Getting heavy. Hit <b>Compact</b> at the next break, or close it if the task is done.'}</div>` : ''}

package/web/styles.css

@@ -367,6 +367,9 @@ table.tbl .sub { font-size:10.5px; color:var(--muted); }
 .live-msg.ok { color: var(--good-ink); } .live-msg.err { color: var(--critical-ink); }
 .item.gone { opacity: .45; }
 
+/* An explicit display beats the hidden attribute, so the panel has to opt back
+   out or it is permanently open. */
+.handover[hidden] { display: none; }
 .handover { margin-top: 8px; padding: 10px; border: 1px dashed var(--border); border-radius: 8px; display: grid; gap: 8px; }
 .handover textarea { width: 100%; box-sizing: border-box; font: inherit; font-size: 12.5px; padding: 8px; border-radius: 6px;
   border: 1px solid var(--border); background: transparent; color: inherit; resize: vertical; }
@@ -417,3 +420,8 @@ table.tbl .sub { font-size:10.5px; color:var(--muted); }
            overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .who .em, .who .pl { font-size:10px; color:var(--muted); line-height:1.35;
                      overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+
+/* Live model advice on a running session: it is an opportunity, not a problem,
+   so it reads as a note with an accent edge rather than a warning. */
+.switch-tip { border-left: 2px solid var(--accent, #eb6834); padding-left: 9px; }
+.switch-tip .act { margin-left: 8px; }