claude-finops 0.5.0 → 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/api.py

@@ -323,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.5.0",
+  "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

@@ -1644,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; }