claude-finops 0.1.0 → 0.2.0

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,9 @@ class Handler(BaseHTTPRequestHandler):
             self.send_json({"error": traceback.format_exc()}, 500)
 
     def api(self, route, qs):
+        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)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-finops",
-  "version": "0.1.0",
+  "version": "0.2.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/web/app.js

@@ -1510,13 +1510,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 +1549,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 +1569,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 +1593,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 +1633,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 +1641,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); }