claude-finops 0.5.0 → 0.7.0

package/README.md

@@ -287,6 +287,45 @@ 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/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/api.py

@@ -113,6 +113,15 @@ class Handler(BaseHTTPRequestHandler):
             if path.startswith("/api/live/"):
                 self._payload = payload
                 return self.session_action(path)
+            if path == "/api/trial/run":
+                # Spends real money and drives a real agent, so it is guarded like
+                # the other side-effecting routes and only ever reached by a click.
+                if not self._same_origin():
+                    return self.send_json({"ok": False, "error": "forbidden"}, 403)
+                from .trial import run
+                return self.send_json(run(payload.get("category"), payload.get("model"),
+                                          payload.get("prompts") or [],
+                                          cwd=payload.get("cwd") or None))
             if path.startswith("/api/do/"):
                 if not self._same_origin():
                     return self.send_json({"ok": False, "error": "forbidden"}, 403)
@@ -292,6 +301,11 @@ class Handler(BaseHTTPRequestHandler):
             return self.send_json(a.context_analysis(f))
         if route == "waste":
             return self.send_json(a.waste(f))
+        if route == "trial":
+            from .trial import samples, available
+            return self.send_json({"available": available(),
+                                   "samples": samples(qs.get("category", [""])[0],
+                                                      int(qs.get("limit", ["3"])[0]))})
         if route == "model_evidence":
             return self.send_json(a.model_evidence(f))
         if route == "model_switch":
@@ -323,6 +337,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/finops/trial.py

@@ -0,0 +1,169 @@
+"""Run the trial the evidence asks for, instead of only recommending one.
+
+model_evidence() ends with an honest caveat: your prompts were never randomly
+assigned to models, so a category can simply have been easier on one of them.
+That caveat can only be closed by actually running the same prompt on both
+models and looking at what came back.
+
+So: take real prompts out of your own history, re-run them headlessly on the
+candidate model, and compare what they cost against what they cost the first
+time. `claude -p ... --output-format json` reports cost, turns and errors for
+exactly this purpose.
+
+Two things this deliberately does not do:
+
+  * It never runs anything on its own. A trial spends real money and drives a
+    real agent, so it happens on an explicit click, with the bill shown first.
+  * It runs in a scratch directory by default, not your repo. Headless Claude
+    cannot ask for permission, so tools that need it are denied and recorded —
+    but a trial that edits your working tree to prove a point is not a trial
+    anyone wants.
+"""
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+
+from .advisor import model_alias
+from .paths import DB_PATH
+
+TIMEOUT_S = 600
+MAX_PROMPTS = 5
+MAX_CHARS = 6000          # a prompt longer than this is usually a paste, not a task
+
+
+def samples(category, limit=3):
+    """Real prompts from this category, with what they actually cost first time.
+
+    Picks around the middle of the cost distribution: the cheapest prompts are
+    usually "yes"/"continue" and the most expensive are outliers, and neither
+    tells you much about a model.
+    """
+    from .analytics import Analytics
+    a = Analytics(DB_PATH)
+    rows = a.q("""SELECT p.id, p.text, p.models model, p.est_cost_usd cost,
+        p.request_count turns, p.tool_calls tools, p.session_id, p.day
+        FROM prompts p
+        WHERE COALESCE(p.category,'other') = ? AND p.agent = 'claude'
+          AND p.models IS NOT NULL AND p.models NOT LIKE '%,%'
+          AND p.models != '<synthetic>' AND p.est_cost_usd > 0
+          AND LENGTH(p.text) BETWEEN 40 AND ?
+          -- Things you actually typed. System turns, tool results, queued
+          -- follow-ups and SDK traffic are not tasks anyone would re-run, and
+          -- a trial built from task-notification XML measures nothing.
+          AND p.source = 'typed'
+          AND p.text NOT LIKE '<%' AND p.text NOT LIKE '[Request interrupted%'
+          AND p.text NOT LIKE 'Caveat:%' AND p.text NOT LIKE '%<local-command%' 
+        ORDER BY p.est_cost_usd""", (category, MAX_CHARS))
+    if not rows:
+        return []
+    lo = int(len(rows) * 0.35)
+    hi = max(lo + 1, int(len(rows) * 0.85))
+    mid = rows[lo:hi] or rows
+    step = max(1, len(mid) // limit)
+    picked = mid[::step][:limit]
+    return [{"prompt_id": r["id"], "text": r["text"], "baseline_model": r["model"],
+             "baseline_name": a.pricing.display_name(r["model"]),
+             "baseline_cost_usd": round(r["cost"], 4),
+             "baseline_turns": r["turns"], "baseline_tools": r["tools"],
+             "day": r["day"]} for r in picked]
+
+
+def available():
+    return bool(shutil.which("claude"))
+
+
+def run_one(text, model, cwd=None, timeout=TIMEOUT_S):
+    """One headless run. Returns what it cost and whether it got there."""
+    exe = shutil.which("claude")
+    if not exe:
+        return {"ok": False, "error": "The `claude` CLI is not on PATH."}
+    sandbox = cwd or tempfile.mkdtemp(prefix="finops-trial-")
+    started = time.time()
+    try:
+        p = subprocess.run([exe, "-p", text, "--model", model_alias(model),
+                            "--output-format", "json"],
+                           capture_output=True, text=True, timeout=timeout, cwd=sandbox)
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "error": f"Gave up after {timeout}s.",
+                "elapsed_s": round(time.time() - started, 1)}
+    except OSError as e:
+        return {"ok": False, "error": str(e)}
+    try:
+        d = json.loads(p.stdout)
+    except ValueError:
+        return {"ok": False, "error": (p.stderr or p.stdout or "no output")[:400],
+                "elapsed_s": round(time.time() - started, 1)}
+    usage = d.get("usage") or {}
+    return {
+        "ok": not d.get("is_error"),
+        "cost_usd": d.get("total_cost_usd"),
+        "turns": d.get("num_turns"),
+        "elapsed_s": round(time.time() - started, 1),
+        "duration_api_ms": d.get("duration_api_ms"),
+        "output_tokens": usage.get("output_tokens"),
+        "input_tokens": usage.get("input_tokens"),
+        "denials": len(d.get("permission_denials") or []),
+        "stop_reason": d.get("stop_reason") or d.get("terminal_reason"),
+        "result": (d.get("result") or "")[:4000],
+        "session_id": d.get("session_id"),
+        "sandbox": sandbox,
+    }
+
+
+def _verdict(runs, baseline_cost):
+    """What the runs actually showed, in the same language as the back-test."""
+    done = [r for r in runs if r.get("ok") and r.get("cost_usd") is not None]
+    if not done:
+        return "failed", ("Every run errored or produced nothing, so this says nothing about "
+                          "cost. Check the errors below before reading anything into it.")
+    got = sum(r["cost_usd"] for r in done)
+    base = sum(baseline_cost)
+    denials = sum(r.get("denials") or 0 for r in done)
+    if base <= 0:
+        return "unclear", "No usable baseline cost for these prompts."
+    pct = 100.0 * (1 - got / base)
+    tail = (f" {denials} tool call(s) were denied because a headless run cannot ask for "
+            f"permission, so the real task may be larger than this." if denials else "")
+    if len(done) < len(runs):
+        tail += f" {len(runs) - len(done)} of {len(runs)} runs failed and are excluded."
+    if pct >= 25:
+        return "confirmed", (f"Re-running your own prompts cost {pct:.0f}% less on the cheaper "
+                             f"model (${got:.2f} against ${base:.2f} the first time).{tail}")
+    if pct >= 0:
+        return "marginal", (f"Only {pct:.0f}% cheaper on a re-run (${got:.2f} against "
+                            f"${base:.2f}). Not the saving the history suggested.{tail}")
+    return "contradicted", (f"The re-run cost {abs(pct):.0f}% *more* (${got:.2f} against "
+                            f"${base:.2f}). The history overstated this switch.{tail}")
+
+
+def run(category, model, prompts, cwd=None):
+    """Run a set of sample prompts on a candidate model and judge the result."""
+    if not prompts:
+        return {"ok": False, "error": "Nothing to run."}
+    prompts = prompts[:MAX_PROMPTS]
+    runs, baseline = [], []
+    for item in prompts:
+        text = (item.get("text") or "").strip()
+        if not text:
+            continue
+        r = run_one(text, model, cwd=cwd)
+        r["prompt"] = text[:300]
+        r["baseline_cost_usd"] = item.get("baseline_cost_usd") or 0
+        r["baseline_turns"] = item.get("baseline_turns")
+        runs.append(r)
+        baseline.append(r["baseline_cost_usd"])
+    verdict, why = _verdict(runs, baseline)
+    done = [r for r in runs if r.get("ok") and r.get("cost_usd") is not None]
+    return {
+        "ok": True, "category": category, "model": model, "alias": model_alias(model),
+        "runs": runs, "verdict": verdict, "why": why,
+        "measured_cost_usd": round(sum(r["cost_usd"] for r in done), 4),
+        "baseline_cost_usd": round(sum(baseline), 4),
+        "ran_at": int(time.time()),
+        "note": ("Measured by re-running these exact prompts headlessly. The agent had no "
+                 "permission to use tools that ask, and worked in a scratch directory, so a "
+                 "task that needs your repo will look smaller here than it is."),
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-finops",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -1354,6 +1354,8 @@ function evidenceBody(ev) {
       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>`},
+    {h: '', f: r => `<button class="act ghost trial-btn" data-cat="${esc(r.c.category)}"
+       data-model="${esc(r.x.model)}" data-name="${esc(r.x.name)}">Try it →</button>`},
   ], rows) + `<div class="note" style="padding:10px 14px">${esc(ev.method)}</div>`;
 }
 
@@ -1416,6 +1418,7 @@ VIEWS.modelswitch = async (page) => {
     {h: 'Could save', num: 1, f: r => fmtUSD(r.estimated_savings_usd)},
     {h: 'Why', f: r => esc(r.why)},
   ], m.projects);
+  wireTrials(page);
   addChart(page, 'Savings by switch', el => C.barsH(el, {
     rows: m.switches.slice(0, 10), label: r => clip(`${r.scope} → ${r.recommended_name}`, 48),
     value: r => r.estimated_savings_usd,
@@ -1426,6 +1429,116 @@ VIEWS.modelswitch = async (page) => {
     {badge: BADGE.recommendation, hint: 'Colour = confidence (green high, blue medium, amber low)'});
 };
 
+/* ---------- trial: stop recommending, start measuring ----------
+   The evidence ends at "strong evidence for a trial, not proof". This runs the
+   trial: real prompts out of your own history, re-run headlessly on the
+   candidate model, priced against what they cost the first time. It spends real
+   money, so nothing happens without two clicks. */
+function trialPanelHTML(cat, model, name, s) {
+  if (!s.available) {
+    return `<div class="empty">The <code>claude</code> CLI is not on PATH, so a trial cannot be
+      run from here.</div>`;
+  }
+  if (!s.samples.length) {
+    return `<div class="empty">No prompt you actually typed in this category is short enough to
+      re-run safely.</div>`;
+  }
+  const base = s.samples.reduce((a, x) => a + (x.baseline_cost_usd || 0), 0);
+  return `
+    <div class="dt">These are ${s.samples.length} prompts you really sent in
+      <b>${esc(cat.replace('_', ' '))}</b>. Running them again on <b>${esc(name)}</b> costs money —
+      they cost ${fmtUSD(base)} the first time, and the cheaper model should come in under that.</div>
+    <div class="stack trial-samples">${s.samples.map((x, i) => `
+      <div class="dt trial-s" data-i="${i}">
+        <span class="note">${esc(x.day)} · ${esc(x.baseline_name)} · ${fmtUSD(x.baseline_cost_usd)} ·
+          ${fmtInt(x.baseline_turns)} turns</span>
+        <div class="trial-text">${esc(x.text.slice(0, 400))}${x.text.length > 400 ? '…' : ''}</div>
+      </div>`).join('')}</div>
+    <div class="dt note">Runs headlessly in a scratch directory. Tools that need permission are
+      denied, because a headless agent cannot ask — so a task that needs your repo will look
+      smaller here than it really is.</div>
+    <div class="live-actions">
+      <button class="act trial-run">▶ Run ${s.samples.length} prompts on ${esc(name)}</button>
+      <button class="act ghost trial-copy">Copy the first prompt instead</button>
+      <span class="trial-msg note"></span>
+    </div>
+    <div class="trial-out"></div>`;
+}
+
+const TRIAL_VERDICT = {
+  confirmed:    ['healthy', 'Confirmed by running it'],
+  marginal:     ['high', 'Smaller than advertised'],
+  contradicted: ['critical', 'History overstated it'],
+  failed:       ['critical', 'Runs failed'],
+  unclear:      ['high', 'Inconclusive'],
+};
+
+function trialResultHTML(r) {
+  const v = TRIAL_VERDICT[r.verdict] || TRIAL_VERDICT.unclear;
+  return `<div class="dt"><b>${statusChip(v[0], v[1])}</b> ${esc(r.why)}</div>` + table([
+    {h: 'Prompt', trunc: 1, f: x => esc(x.prompt)},
+    {h: 'First time', num: 1, f: x => fmtUSD(x.baseline_cost_usd)},
+    {h: 'On ' + esc(r.alias), num: 1, f: x => x.ok ? fmtUSD(x.cost_usd) : '—'},
+    {h: 'Turns', num: 1, f: x => x.ok ? fmtInt(x.turns) : '—'},
+    {h: 'Took', num: 1, f: x => x.ok ? x.elapsed_s + 's' : '—'},
+    {h: 'Denied', num: 1, f: x => x.denials ? fmtInt(x.denials) : ''},
+    {h: 'Result', f: x => x.ok ? `<span class="note">${esc((x.result || '').slice(0, 120))}</span>`
+      : `<span class="status critical">${esc((x.error || 'failed').slice(0, 120))}</span>`},
+  ], r.runs) + `<div class="note" style="padding:8px 14px">${esc(r.note)}</div>`;
+}
+
+function wireTrials(page) {
+  page.querySelectorAll('.trial-btn').forEach(b => b.onclick = async () => {
+    const row = b.closest('tr');
+    if (row.nextElementSibling?.classList.contains('trial-row')) {
+      row.nextElementSibling.remove(); return;
+    }
+    const {cat, model, name} = b.dataset;
+    const tr = h(`<tr class="trial-row"><td colspan="10"><div class="trial-panel">
+      <div class="empty">Finding prompts you sent…</div></div></td></tr>`);
+    row.after(tr);
+    const host = tr.querySelector('.trial-panel');
+    let s;
+    try {
+      s = await fetch(`/api/trial?category=${encodeURIComponent(cat)}&limit=3`).then(r => r.json());
+    } catch (e) { host.innerHTML = `<div class="empty">${esc(e.message)}</div>`; return; }
+    host.innerHTML = trialPanelHTML(cat, model, name, s);
+    const msg = host.querySelector('.trial-msg');
+    host.querySelector('.trial-copy')?.addEventListener('click', async () => {
+      try { await navigator.clipboard.writeText(s.samples[0].text); msg.textContent = 'Copied.'; }
+      catch { msg.textContent = 'Could not copy.'; }
+    });
+    host.querySelector('.trial-run')?.addEventListener('click', async ev => {
+      const btn = ev.currentTarget;
+      if (btn.dataset.armed !== '1') {
+        btn.dataset.armed = '1';
+        btn.textContent = 'Click again to spend real money';
+        btn.classList.add('warn');
+        return;
+      }
+      btn.disabled = true;
+      btn.textContent = 'Running…';
+      msg.textContent = 'Each prompt runs to completion; this can take a few minutes.';
+      try {
+        const r = await fetch('/api/trial/run', {
+          method: 'POST',
+          headers: {'X-FinOps-Action': '1', 'Content-Type': 'application/json'},
+          body: JSON.stringify({category: cat, model, prompts: s.samples}),
+        }).then(x => x.json());
+        host.querySelector('.trial-out').innerHTML = r.ok
+          ? trialResultHTML(r) : `<div class="empty">${esc(r.error || 'failed')}</div>`;
+        msg.textContent = '';
+      } catch (e) {
+        msg.textContent = e.message;
+      }
+      btn.disabled = false;
+      btn.classList.remove('warn');
+      btn.textContent = '▶ Run again';
+      btn.dataset.armed = '';
+    });
+  });
+}
+
 /* ---------- waste ---------- */
 VIEWS.waste = async (page) => {
   const w = await api('waste');
@@ -1644,6 +1757,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,18 @@ 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; }
+
+/* Trial panel: an experiment you are about to pay for, so it reads as a quiet
+   workbench rather than another recommendation. */
+.trial-row > td { padding: 0 !important; background: var(--surface-2); }
+.trial-panel { padding: 12px 14px; display: grid; gap: 8px;
+               border-left: 2px solid var(--accent, #eb6834); }
+.trial-text { font-size: 12px; margin-top: 3px; white-space: pre-wrap;
+              max-height: 76px; overflow: auto; color: var(--text-2); }
+.trial-s { border-top: 1px solid var(--border); padding-top: 7px; }
+.trial-out:empty { display: none; }