claude-finops 0.1.0 → 0.3.0

package/README.md

@@ -290,8 +290,15 @@ place for you to delete once you are happy.
 ## Privacy
 
 `~/.claude-finops/data/finops.db` and the prompt/CSV exports contain **your full prompt text**. The
-server binds to `127.0.0.1` only and makes no outbound requests, but treat the
-database and any export you generate as sensitive.
+server binds to `127.0.0.1` only, but treat the database and any export you
+generate as sensitive.
+
+The app makes exactly one outbound request of its own: once a day it asks
+`registry.npmjs.org` what the latest `claude-finops` version is, so it can tell
+you when an upgrade is out (npm has no way to push one at you). It sends nothing
+about you or your usage. Turn it off with `NO_UPDATE_NOTIFIER=1` or
+`CLAUDE_FINOPS_NO_UPDATE_CHECK=1`. Provider cost APIs are called only if you
+configure a key with `--set-key`.
 
 ---
 

package/finops/api.py

@@ -177,7 +177,7 @@ class Handler(BaseHTTPRequestHandler):
         return self.send_json({"error": "unknown route"}, 404)
 
     def session_action(self, path):
-        """POST /api/live/<pid>/<interrupt|close|kill>.
+        """POST /api/live/<pid>/<interrupt|close|kill|compact|handover>.
 
         Guarded against cross-site requests: a custom header can't be sent by another
         origin without a CORS preflight (which this server never approves), and any
@@ -195,12 +195,16 @@ class Handler(BaseHTTPRequestHandler):
         agent = (self._payload or {}).get("agent") or "claude"
         if agent != "claude":
             from .procs import act_agent
-            if parts[3] == "handover":
-                return self.send_json({"ok": False, "error": "Hand over is only available for Claude Code."})
+            if parts[3] in ("handover", "compact"):
+                return self.send_json({"ok": False,
+                                       "error": f"{parts[3].capitalize()} is only available for Claude Code."})
             return self.send_json(act_agent(int(parts[2]), parts[3], agent))
         if parts[3] == "handover":
             from .procs import handover
             return self.send_json(handover(int(parts[2]), self._payload))
+        if parts[3] == "compact":
+            from .procs import compact
+            return self.send_json(compact(int(parts[2]), self._payload))
         return self.send_json(act(int(parts[2]), parts[3]))
 
     def do_GET(self):
@@ -222,6 +226,12 @@ class Handler(BaseHTTPRequestHandler):
             self.send_json({"error": traceback.format_exc()}, 500)
 
     def api(self, route, qs):
+        if route == "update":
+            from .update import check
+            return self.send_json(check(force=qs.get("refresh", [""])[0] == "1"))
+        if route == "usage":
+            from .limits import usage
+            return self.send_json(usage(force=qs.get("refresh", [""])[0] == "1"))
         if route.startswith(("free_models", "suggestions", "job/", "sync", "compare")):
             return self.actions_get(route)
         f = filters_from(qs)
@@ -399,6 +409,11 @@ def _sync_job(log):
     return {"built_at": A.q("SELECT value FROM meta WHERE key='built_at'")[0]["value"]}
 
 
+def _notify_update():
+    from .update import notify
+    notify()
+
+
 def serve(port=8787, db=DB_PATH, background=None):
     global A
     if not os.path.exists(db):
@@ -413,6 +428,8 @@ def serve(port=8787, db=DB_PATH, background=None):
     print(f"  warehouse: {db}")
     print(f"  data      : {A.first_day} .. {A.last_day}")
     print("  Ctrl-C to stop.")
+    # Off the main thread: a slow registry must never delay the dashboard.
+    threading.Thread(target=_notify_update, daemon=True).start()
     try:
         srv.serve_forever()
     except KeyboardInterrupt:

package/finops/limits.py

@@ -0,0 +1,105 @@
+"""Current plan usage, as `/usage` reports it.
+
+Claude Code owns those numbers (5-hour session window and weekly windows); they
+are not in any file on this machine. The one way to read them without an account
+API is to ask Claude Code itself:
+
+    claude -p "/usage" --output-format json
+
+That runs the local slash command, spends no tokens and makes no model call, and
+returns the same text `/usage` prints in the TUI. The reply is parsed here and
+cached briefly so the dashboard never shells out on every render.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+
+from .paths import DATA_DIR, ensure_dirs
+
+CACHE = os.path.join(DATA_DIR, "usage_cache.json")
+TTL_S = 120
+TIMEOUT_S = 90
+
+# "Current session: 0% used · resets Sep 22 at 2:40pm (Asia/Calcutta)"
+_LIMIT = re.compile(r"^(?P<label>[^:]+?):\s*(?P<pct>\d+(?:\.\d+)?)%\s*used"
+                    r"(?:\s*[·-]\s*resets\s*(?P<resets>.+?))?\s*$")
+# "  40% of your usage was at >150k context"   /   "  Top skills: /run 2%"
+_WINDOW = re.compile(r"^Last\s+(?P<window>\S+)\s*·\s*(?P<detail>.+)$")
+
+
+def _parse(text):
+    limits, windows, cur = [], [], None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        m = _WINDOW.match(line)
+        if m:
+            cur = {"window": m.group("window"), "detail": m.group("detail"), "notes": []}
+            windows.append(cur)
+            continue
+        m = _LIMIT.match(line)
+        if m and line.lower().startswith("current"):
+            limits.append({"label": m.group("label").strip(),
+                           "pct": float(m.group("pct")),
+                           "resets": (m.group("resets") or "").strip()})
+            cur = None
+            continue
+        if cur is not None and raw.startswith((" ", "\t")):
+            cur["notes"].append(line)
+    return limits, windows
+
+
+def _run():
+    exe = shutil.which("claude")
+    if not exe:
+        return {"ok": False, "error": "`claude` is not on PATH, so /usage can't be read here."}
+    try:
+        p = subprocess.run([exe, "-p", "/usage", "--output-format", "json"],
+                           capture_output=True, text=True, timeout=TIMEOUT_S,
+                           cwd=os.path.expanduser("~"))
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "error": f"`claude -p /usage` did not answer within {TIMEOUT_S}s."}
+    except OSError as e:
+        return {"ok": False, "error": f"Could not run `claude`: {e}"}
+    if p.returncode != 0:
+        return {"ok": False, "error": (p.stderr or p.stdout or "claude exited non-zero").strip()[:400]}
+    try:
+        text = (json.loads(p.stdout) or {}).get("result") or ""
+    except ValueError:
+        return {"ok": False, "error": "Could not parse the reply from `claude -p /usage`."}
+    if not text.strip():
+        return {"ok": False, "error": "`/usage` returned nothing."}
+    limits, windows = _parse(text)
+    return {"ok": True, "limits": limits, "windows": windows, "text": text,
+            "fetched_at": time.time(),
+            "note": "Read from Claude Code's own /usage. Percentages are plan limits, not cost; "
+                    "the contributing-behaviour lines cover local sessions on this machine only."}
+
+
+def usage(force=False):
+    """Cached /usage. Reads the cache unless it is stale or `force` is set."""
+    ensure_dirs()
+    cached = None
+    try:
+        with open(CACHE) as fh:
+            cached = json.load(fh)
+    except (OSError, ValueError):
+        pass
+    if cached and cached.get("ok") and not force and time.time() - cached.get("fetched_at", 0) < TTL_S:
+        return dict(cached, cached=True, age_s=int(time.time() - cached["fetched_at"]))
+    res = _run()
+    if res.get("ok"):
+        try:
+            with open(CACHE, "w") as fh:
+                json.dump(res, fh)
+        except OSError:
+            pass
+        return dict(res, cached=False, age_s=0)
+    if cached and cached.get("ok"):          # keep showing the last good read
+        return dict(cached, cached=True, stale=True, error=res.get("error"),
+                    age_s=int(time.time() - cached["fetched_at"]))
+    return res

package/finops/procs.py

@@ -497,3 +497,163 @@ def handover(pid, opts):
         res["closed"] = act(pid, "close")
         res["message"] += " Old session closed (resumable)."
     return res
+
+
+# ------------------------------------------------------------------ compact ----
+# /compact is typed *into* the running session — there is no signal for it. Nothing
+# can write to another process's terminal directly (TIOCSTI is off on macOS and on
+# modern Linux), so the keystrokes are handed to whatever owns that terminal:
+# tmux if the session runs inside one, else Terminal.app or iTerm2 via
+# AppleScript, else Windows Terminal/console via SendKeys. When none of those owns
+# it, the UI falls back to copying the command for you to paste.
+
+def _tty_of(pid):
+    """Controlling terminal of a pid, as a device path ('/dev/ttys004')."""
+    if os.name == "nt":
+        return ""
+    try:
+        t = subprocess.run(["ps", "-o", "tty=", "-p", str(pid)],
+                           capture_output=True, text=True, timeout=10).stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    if not t or t in ("?", "??", "-"):
+        return ""
+    return t if t.startswith("/dev/") else "/dev/" + t
+
+
+def _send_tmux(tty, pid, text):
+    if not shutil.which("tmux"):
+        return False, ""
+    try:
+        out = subprocess.run(["tmux", "list-panes", "-a", "-F",
+                              "#{pane_tty}\t#{pane_pid}\t#{session_name}:#{window_index}.#{pane_index}"],
+                             capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.TimeoutExpired):
+        return False, ""
+    if out.returncode != 0:
+        return False, ""
+    procs = _ps()
+    for line in out.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        pane_tty, pane_pid, target = parts
+        if pane_tty != tty and not (pane_pid.isdigit() and int(pane_pid) in _ancestors(pid, procs)):
+            continue
+        r = subprocess.run(["tmux", "send-keys", "-t", target, "--", text],
+                           capture_output=True, text=True)
+        if r.returncode:
+            return False, (r.stderr or "").strip()
+        subprocess.run(["tmux", "send-keys", "-t", target, "Enter"], capture_output=True)
+        return True, "tmux"
+    return False, ""
+
+
+def _send_macos(tty, text):
+    """Terminal.app / iTerm2 both expose each tab's tty, so the right one is addressable."""
+    if sys.platform != "darwin" or not tty:
+        return False, ""
+    t = json.dumps(text)
+    dev = json.dumps(tty)
+    osa_terminal = f'''
+      tell application "System Events" to set running_ to (exists process "Terminal")
+      if running_ then
+        tell application "Terminal"
+          repeat with w in windows
+            repeat with tb in tabs of w
+              if (tty of tb) is {dev} then
+                do script {t} in tb
+                return "ok"
+              end if
+            end repeat
+          end repeat
+        end tell
+      end if
+      return "no"'''
+    osa_iterm = f'''
+      tell application "System Events" to set running_ to (exists process "iTerm2")
+      if running_ then
+        tell application "iTerm2"
+          repeat with w in windows
+            repeat with tb in tabs of w
+              repeat with s in sessions of tb
+                if (tty of s) is {dev} then
+                  tell s to write text {t}
+                  return "ok"
+                end if
+              end repeat
+            end repeat
+          end repeat
+        end tell
+      end if
+      return "no"'''
+    for script, who in ((osa_terminal, "Terminal.app"), (osa_iterm, "iTerm2")):
+        try:
+            r = subprocess.run(["osascript", "-e", script], capture_output=True, text=True, timeout=25)
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        if r.returncode == 0 and r.stdout.strip() == "ok":
+            return True, who
+        if r.returncode and "not allowed" in (r.stderr or "").lower():
+            return False, ("macOS blocked the keystroke: allow this terminal under System Settings → "
+                           "Privacy & Security → Automation.")
+    return False, ""
+
+
+def _send_windows(pid, text):
+    """Windows: focus the session's console window, then SendKeys into it."""
+    if os.name != "nt":
+        return False, ""
+    ps = ('$ErrorActionPreference="Stop";'
+          'Add-Type -AssemblyName Microsoft.VisualBasic;'
+          'Add-Type -AssemblyName System.Windows.Forms;'
+          f'$p=Get-Process -Id {pid};'
+          '$h=$p.MainWindowHandle;'
+          'while($h -eq 0 -and $p.Parent){$p=$p.Parent;$h=$p.MainWindowHandle};'
+          'if($h -eq 0){"no";exit};'
+          '[Microsoft.VisualBasic.Interaction]::AppActivate($p.Id);'
+          'Start-Sleep -Milliseconds 300;'
+          f'[System.Windows.Forms.SendKeys]::SendWait({json.dumps(text)}+"{{ENTER}}");"ok"')
+    try:
+        r = subprocess.run(["powershell", "-NoProfile", "-Command", ps],
+                           capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired):
+        return False, ""
+    return (r.returncode == 0 and r.stdout.strip().endswith("ok")), ""
+
+
+def compact(pid, opts=None):
+    """Type `/compact` into a running Claude Code session's terminal.
+
+    opts: instructions – optional focus for the summary ("/compact <instructions>")
+    """
+    opts = opts or {}
+    extra = " ".join((opts.get("instructions") or "").split())[:400]
+    text = "/compact" + (f" {extra}" if extra else "")
+    try:
+        with open(os.path.join(REG, f"{pid}.json")) as fh:
+            reg = json.load(fh)
+    except (OSError, ValueError):
+        return {"ok": False, "error": "Not a registered Claude Code session.", "copy": text}
+    p = _ps().get(pid)
+    if not p or not _is_claude(p):
+        return {"ok": False, "error": "Process is no longer running.", "copy": text}
+    if reg.get("procStart") and reg["procStart"] != p["lstart"]:
+        return {"ok": False, "error": "PID was reused by another process; refusing.", "copy": text}
+
+    tty = _tty_of(pid)
+    hint = ""
+    for send in (lambda: _send_tmux(tty, pid, text),
+                 lambda: _send_macos(tty, text),
+                 lambda: _send_windows(pid, text)):
+        ok, info = send()
+        if ok:
+            return {"ok": True, "message": f"Sent `{text}` to the session"
+                                           f"{f' via {info}' if info else ''}. "
+                                           "It compacts on its next turn; watch that window.",
+                    "sent": True, "copy": text}
+        if info and not hint:
+            hint = info
+    return {"ok": False, "sent": False, "copy": text,
+            "error": (hint or "Couldn't reach that session's terminal") +
+                     f" — `{text}` is on your clipboard; paste it in that window."}

package/finops/update.py

@@ -0,0 +1,133 @@
+"""Is there a newer release on npm?
+
+npm has no way to push: a global install stays on whatever version it was
+installed at until someone runs `npm i -g claude-finops@latest`. So we ask the
+registry ourselves, once a day, and say so if there is something newer.
+
+This is the only outbound request the app makes on its own. It sends nothing
+about you — no identifiers, no usage, not even a User-Agent beyond the package
+name and the version you already published to npm by installing it. Turn it off
+with NO_UPDATE_NOTIFIER=1 (the ecosystem-wide convention) or
+CLAUDE_FINOPS_NO_UPDATE_CHECK=1.
+
+The answer is cached in ~/.claude-finops/data/update_cache.json for a day, so a
+dashboard that restarts twenty times makes one request. Every failure is
+silent: no network, a proxy, an offline laptop and a 500 from the registry all
+look the same to the caller, which is "we don't know", never an error.
+"""
+import json
+import os
+import re
+import time
+import urllib.request
+
+from .paths import DATA_DIR, ROOT, ensure_dirs
+
+CACHE = os.path.join(DATA_DIR, "update_cache.json")
+URL = "https://registry.npmjs.org/claude-finops/latest"
+TTL_S = 24 * 60 * 60
+TIMEOUT_S = 3
+
+_NUM = re.compile(r"\d+")
+
+
+def _installed():
+    """Our own version, from the package.json we ship next to the code."""
+    try:
+        with open(os.path.join(ROOT, "package.json")) as fh:
+            return str(json.load(fh).get("version") or "").strip()
+    except (OSError, ValueError):
+        return ""
+
+
+def _key(v):
+    """Compare 1.10.0 above 1.9.0, and treat 1.0.0-rc.1 as below 1.0.0.
+
+    Only the numeric core is ordered; a prerelease suffix just loses the tie.
+    That is enough for a notifier — we publish plain releases.
+    """
+    core, _, pre = str(v).partition("-")
+    nums = [int(n) for n in _NUM.findall(core)[:3]]
+    return (nums + [0, 0, 0])[:3], 0 if pre else 1
+
+
+def _newer(latest, current):
+    return bool(latest) and bool(current) and _key(latest) > _key(current)
+
+
+def _read_cache():
+    try:
+        with open(CACHE) as fh:
+            c = json.load(fh)
+        return c if isinstance(c, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_cache(latest):
+    ensure_dirs()
+    tmp = CACHE + ".tmp"
+    try:
+        with open(tmp, "w") as fh:
+            json.dump({"latest": latest, "checked_at": int(time.time())}, fh)
+        os.replace(tmp, CACHE)
+    except OSError:
+        pass
+
+
+def _fetch():
+    req = urllib.request.Request(URL, headers={
+        "Accept": "application/json",
+        "User-Agent": f"claude-finops/{_installed() or '0'}",
+    })
+    with urllib.request.urlopen(req, timeout=TIMEOUT_S) as r:
+        return str(json.load(r).get("version") or "").strip()
+
+
+def disabled():
+    return bool(os.environ.get("NO_UPDATE_NOTIFIER")
+                or os.environ.get("CLAUDE_FINOPS_NO_UPDATE_CHECK"))
+
+
+def check(force=False):
+    """Return {current, latest, update_available, checked_at, ...}.
+
+    Reads the cache unless it is older than a day (or `force`). Never raises,
+    and never blocks longer than TIMEOUT_S.
+    """
+    current = _installed()
+    out = {"current": current, "latest": "", "update_available": False,
+           "command": "npm i -g claude-finops@latest", "checked_at": 0,
+           "disabled": disabled()}
+    if out["disabled"]:
+        return out
+
+    cache = _read_cache()
+    age = time.time() - float(cache.get("checked_at") or 0)
+    if cache.get("latest") and age < TTL_S and not force:
+        out.update(latest=cache["latest"], checked_at=int(cache["checked_at"]), cached=True)
+    else:
+        try:
+            latest = _fetch()
+        except Exception:
+            # Offline, blocked, rate-limited — fall back to the last good answer
+            # rather than telling anyone anything is wrong.
+            latest = str(cache.get("latest") or "")
+            out["checked_at"] = int(cache.get("checked_at") or 0)
+            out["stale"] = True
+        else:
+            _write_cache(latest)
+            out["checked_at"] = int(time.time())
+        out["latest"] = latest
+    out["update_available"] = _newer(out["latest"], current)
+    return out
+
+
+def notify(log=print):
+    """Print one line if a newer version is out. Safe to call from a thread."""
+    try:
+        u = check()
+    except Exception:
+        return
+    if u.get("update_available"):
+        log(f"  update    : {u['current']} -> {u['latest']}   {u['command']}")

package/package.json

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

@@ -100,6 +100,7 @@ Environment:
   CLAUDE_FINOPS_HOME=/path      where your data lives (default ~/.claude-finops)
   CLAUDE_PROJECTS=/path         where to read transcripts from
   CLAUDE_FINOPS_PYTHON=/path    which Python the npm wrapper should use
+  NO_UPDATE_NOTIFIER=1          never check npm for a newer release
 """
 
 

package/web/app.js

@@ -160,6 +160,7 @@ function shell() {
           <span class="spacer"></span>
           <div class="search"><span class="mag">⌕</span>
             <input id="gsearch" placeholder="Search prompts, sessions, models, dates…"></div>
+          <button class="iconbtn upd" id="upd" hidden></button>
           <button class="iconbtn" id="tour-btn" title="Walk through this dashboard">? Tour</button>
           <button class="iconbtn" id="theme" title="Toggle theme">◐</button>
           <button class="iconbtn" id="refresh" title="Reload data">↻</button>
@@ -182,6 +183,7 @@ function shell() {
     render();
   };
   $('#refresh').onclick = () => { bust(); render(); };
+  updateChip();
   $('#sync').onclick = runSync;
   syncLabel();
   let t;
@@ -190,6 +192,28 @@ function shell() {
       else if (S.view === 'search') go('overview'); }, 260); };
 }
 
+/* ---------- update notice ----------
+   npm cannot push a new release at anyone, so the server asks the registry once
+   a day and we surface the answer here. Silent when you are current, when the
+   check is switched off, and when it simply could not reach the registry. */
+async function updateChip() {
+  const el = $('#upd');
+  if (!el) return;
+  let u;
+  try { u = await fetch('/api/update').then(r => r.json()); } catch { return; }
+  if (!u || !u.update_available) return;
+  el.hidden = false;
+  el.textContent = `↑ v${u.latest} available`;
+  el.title = `You are on ${u.current}. Click to copy:  ${u.command}`;
+  el.onclick = async () => {
+    try {
+      await navigator.clipboard.writeText(u.command);
+      el.textContent = '✓ command copied';
+      setTimeout(() => { el.textContent = `↑ v${u.latest} available`; }, 2200);
+    } catch { prompt('Run this to upgrade:', u.command); }
+  };
+}
+
 /* ---------- filter bar ---------- */
 const RANGES = [['today', 'Today'], ['7d', '7 days'], ['14d', '14 days'], ['30d', '30 days'],
   ['period', 'Billing period'], ['all', 'All time'], ['custom', 'Custom']];
@@ -1510,13 +1534,37 @@ async function sessionAction(pid, action, body = {}) {
     headers: {'X-FinOps-Action': '1', 'Content-Type': 'application/json'}, body: JSON.stringify(body)});
   return r.json();
 }
+// Plan limits as `/usage` reports them: asked of Claude Code itself, server-side.
+const usageSev = p => p >= 90 ? 'critical' : p >= 75 ? 'approaching' : p >= 50 ? 'high' : 'healthy';
+const usageBody = u => {
+  if (!u || !u.ok) return `<div class="empty">${esc((u && u.error) || 'Usage is unavailable')}</div>`;
+  const meters = (u.limits || []).map(l => `
+    <div class="item">
+      <div class="hd"><b>${esc(l.label)}</b><span class="spacer"></span>
+        <span style="font-variant-numeric:tabular-nums">${fmtPct(l.pct)} used</span></div>
+      <div class="meter ${usageSev(l.pct)}"><i style="width:${Math.min(100, l.pct)}%"></i></div>
+      ${l.resets ? `<div class="dt note">Resets ${esc(l.resets)}</div>` : ''}</div>`).join('')
+    || `<pre class="note">${esc(u.text || '')}</pre>`;
+  const windows = (u.windows || []).map(w => `
+    <div class="item"><div class="hd">Last ${esc(w.window)}<span class="spacer"></span>
+      <span class="note">${esc(w.detail)}</span></div>
+      ${(w.notes || []).map(n => `<div class="dt">• ${esc(n)}</div>`).join('')}</div>`).join('');
+  return `<div class="stack">${meters}${windows}</div>
+    <div class="note">${esc(u.note || '')}${u.cached ? ` · read ${dur(u.age_s)} ago` : ''}${u.stale
+      ? ` · <b>last good read</b> (refresh failed: ${esc(u.error || '')})` : ''}</div>`;
+};
 VIEWS.live = async (page) => {
-  const res = await fetch('/api/live?agents=' + encodeURIComponent(S.filter.agents.join(','))).then(r => r.json());   // never cached: always live
+  const [res, usage0] = await Promise.all([
+    fetch('/api/live?agents=' + encodeURIComponent(S.filter.agents.join(','))).then(r => r.json()),   // never cached: always live
+    fetch('/api/usage').then(r => r.json()).catch(e => ({ok: false, error: e.message}))]);
   const list = res.sessions || [];
   const agentName = id => ((S.opts?.agents || []).find(a => a.id === id) || {}).name || id;
   const busy = list.filter(x => x.status === 'busy');
   const sevOf = x => x.severity === 'high' ? 'high' : x.severity === 'medium' ? 'medium' : 'low';
   page.innerHTML = `
+    ${card('Plan usage right now', `<div id="live-usage">${usageBody(usage0)}</div>`,
+      {badge: BADGE.actual, hint: 'Claude Code\'s own /usage: plan limits, not cost. Costs no tokens.',
+       actions: '<button class="btn pb-copy" id="usage-refresh">↻ Refresh usage</button>'})}
     <div class="grid g4">
       ${kpi('Running sessions', fmtInt(list.length), `${busy.length} working right now`, {badge: BADGE.actual})}
       ${kpi('Working (spending now)', fmtInt(busy.length), 'Only these consume tokens right now')}
@@ -1525,6 +1573,8 @@ VIEWS.live = async (page) => {
     </div>
     <div class="note"><b>Idle sessions don't use tokens</b>; they only cost again when you send the next message,
       which re-reads their whole context. <b>Interrupt</b> stops the current turn (like Esc).
+      <b>Compact</b> types <code>/compact</code> into that session's terminal (tmux, Terminal.app, iTerm2 or
+      Windows console; anywhere else it lands on your clipboard to paste).
       <b>Close</b> exits the session cleanly; copy its resume command to bring it back.
       <b>Force kill</b> is for a session that won't close. Each button asks you to click twice.
       Codex, Gemini and Cursor keep no session registry, so they count as running when their transcript was
@@ -1543,9 +1593,10 @@ VIEWS.live = async (page) => {
           <span class="note">${esc(x.cwd)}</span></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. /compact at the next break, or close it if the task is done.'}</div>` : ''}
+          : 'Getting heavy. Hit <b>Compact</b> at the next break, or close it if the task is done.'}</div>` : ''}
         <div class="live-actions">
           ${x.signalable ? `<button class="act" data-a="interrupt" ${x.status !== 'busy' ? 'disabled title="Nothing running"' : ''}>⏸ Interrupt</button>
+          ${x.agent === 'claude' ? '<button class="act" data-a="compact" title="Types /compact into that session\'s terminal">🗜 Compact</button>' : ''}
           <button class="act warn" data-a="close">⏹ Close session</button>
           <button class="act danger" data-a="kill">✖ Force kill</button>` : `<span class="note">${x.agent === 'cursor' ? 'Runs inside the Cursor IDE: stop it there.' : 'No matching process found: stop it in its terminal.'}</span>`}
           ${x.resume ? `<button class="act ghost" data-copy="${esc(x.resume)}">Copy resume command</button>` : ''}
@@ -1566,6 +1617,15 @@ VIEWS.live = async (page) => {
         </div>`}
       </div>`).join('') || `<div class="empty">No ${esc(agentWord())} sessions are running</div>`}</div>`;
   $('#live-refresh', page).onclick = () => render();
+  const ub = $('#usage-refresh', page);
+  ub.onclick = async () => {
+    ub.disabled = true; ub.textContent = 'Reading…';
+    try {
+      const u = await fetch('/api/usage?refresh=1').then(r => r.json());
+      $('#live-usage', page).innerHTML = usageBody(u);
+    } catch (e) { $('#live-usage', page).innerHTML = `<div class="empty">${esc(e.message)}</div>`; }
+    ub.disabled = false; ub.textContent = '↻ Refresh usage';
+  };
   page.querySelectorAll('.item[data-i]').forEach(row => {
     const x = list[+row.dataset.i], pid = x.pid, msg = row.querySelector('.live-msg');
     const ho = row.querySelector('.handover'), ta = ho?.querySelector('textarea'), hoOut = ho?.querySelector('.ho-out');
@@ -1597,7 +1657,7 @@ VIEWS.live = async (page) => {
         if (!b.classList.contains('armed')) {
           row.querySelectorAll('button.armed').forEach(o => { o.classList.remove('armed'); o.textContent = o.dataset.label; });
           b.dataset.label = label; b.classList.add('armed');
-          b.textContent = x.hosts_dashboard && b.dataset.a !== 'interrupt'
+          b.textContent = x.hosts_dashboard && !['interrupt', 'compact'].includes(b.dataset.a)
             ? 'Sure? This is the session that launched the dashboard (the dashboard keeps running)' : `Click again to ${b.dataset.a}`;
           setTimeout(() => { if (b.classList.contains('armed')) { b.classList.remove('armed'); b.textContent = label; } }, 4000);
           return;
@@ -1605,6 +1665,7 @@ VIEWS.live = async (page) => {
         b.classList.remove('armed'); b.disabled = true; b.textContent = 'Working…';
         try {
           const r = await sessionAction(pid, b.dataset.a, {agent: x.agent});
+          if (!r.ok && r.copy) { try { await navigator.clipboard.writeText(r.copy); } catch {} }
           msg.textContent = r.ok ? r.message : `Failed: ${r.error}`;
           msg.className = 'live-msg ' + (r.ok ? 'ok' : 'err');
           if (r.ok && r.exited) { row.classList.add('gone'); setTimeout(() => render(), 1500); }

package/web/styles.css

@@ -385,3 +385,13 @@ table.tbl .sub { font-size:10.5px; color:var(--muted); }
 #tour .tour-ft .spacer { flex: 1; }
 #tour .act.primary { background: var(--accent, #eb6834); border-color: var(--accent, #eb6834); color: #fff; }
 #tour .act[disabled] { opacity: .45; cursor: default; }
+
+/* Update notice in the topbar: present, never alarming — this is good news,
+   not a problem, so it borrows the accent colour rather than the warning one. */
+.iconbtn.upd {
+  border-color: var(--accent, #eb6834);
+  color: var(--accent, #eb6834);
+  font-weight: 600;
+  white-space: nowrap;
+}
+.iconbtn.upd:hover { background: var(--accent, #eb6834); color: #fff; }