meksus 0.4.0 → 0.5.0

package/README.md

@@ -35,6 +35,14 @@ meksus watch --label "build" -- npm run build # any command; a failure opens an
 
 Start a new Claude Code session after installing the hooks. It then appears on the dashboard's **Agents** page: working, waiting for you, finished, or stuck.
 
+## Claude plan limits on the dashboard
+
+```sh
+meksus statusline install --global   # once per computer (use --replace if you already have a status line)
+```
+
+Claude Code's status line then shows how much of your plan's 5-hour and weekly limits you've used and when each resets, and the dashboard's **Agents** page shows the same with a live countdown. A Discord DM tells you when a limit resets (turn it off on the Agents page). Claude Code provides these numbers for claude.ai Pro and Max plans, after the first reply in a session.
+
 ## Check
 
 ```sh
@@ -53,6 +61,10 @@ With `meksus task-lines` turned on (it's off by default), two more things are se
 
 The server scrubs anything that looks like a secret.
 
+When a Claude turn finishes, three numbers describe its size: how long it took, how many tool calls it made and how many files it changed (counted locally; file names never leave). Discord channels can then ask for big or small finished tasks only.
+
+With `meksus statusline` installed, your Claude plan limits are sent too: the used percentage and reset time of the 5-hour and weekly windows, at most once a minute. Nothing else from the status line is sent.
+
 ## Commands
 
 | Command | What it does |
@@ -65,6 +77,7 @@ The server scrubs anything that looks like a secret.
 | `meksus project use <owner/project>` | Write this repo's `.meksus` |
 | `meksus hooks install` / `uninstall` | Watch Claude Code in this repo |
 | `meksus task-lines off \| steps \| prompt` | Opt-in one-line "working on" |
+| `meksus statusline install [--global]` / `uninstall` | Claude plan limits in the status line and on the dashboard |
 | `meksus watch [--label <name>] -- <cmd>` | Run a command and report how it ends |
 
 © Lore Inc. All rights reserved.

package/bin/meksus.mjs

@@ -7,6 +7,7 @@ import { apiBase, dir, readConfig } from "../src/config.mjs";
 import { projectCommand, readProjectFile } from "../src/project.mjs";
 import { incidentCommand, printCards } from "../src/cards.mjs";
 import { flush } from "../src/spool.mjs";
+import { limitsFlush, runStatusline, statuslineCommand } from "../src/statusline.mjs";
 import { taskLinesCommand } from "../src/tasks.mjs";
 import { VERSION } from "../src/version.mjs";
 import { watch } from "../src/watch.mjs";
@@ -22,6 +23,8 @@ const HELP = `M.E.K.S.U.S. CLI ${VERSION}
   meksus project use <owner/project>              Write this repo's .meksus file (commit it)
   meksus hooks install | uninstall                Watch Claude Code in the current repository
   meksus task-lines [off | steps | prompt]        Show what Claude is working on, in one line (opt-in)
+  meksus statusline install [--global]            Claude's plan limits (5-hour and weekly) in Claude Code's
+                                                  status line and on your M.E.K.S.U.S. dashboard
   meksus watch [--label <name>] -- <cmd> …        Run a command and report its status; a failure opens an incident
 
 Status only: code, prompts and command output never leave your machine. With task-lines on, the title
@@ -48,6 +51,10 @@ switch (command) {
     break;
   case "hook": code = await runHook(); break; // called by Claude Code, silent
   case "task-lines": code = taskLinesCommand(rest); break;
+  case "statusline":
+    code = rest.length ? ((rest[0] === "install" && !(await requireAccess())) ? 1 : statuslineCommand(rest)) : await runStatusline();
+    break;
+  case "limits-flush": await limitsFlush(); break; // internal, detached
   case "flush": await flush(); break; // internal, detached
   case "watch": code = await watch(rest); break;
   case "--version": case "-v": case "version": console.log(VERSION); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meksus",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "M.E.K.S.U.S. CLI: see what your AI coding agents (Claude Code) and builds are doing, live, and get Discord alerts when they fail or need you. Status only: code, prompts and output never leave your machine.",
   "keywords": [
     "meksus",

package/src/hooks.mjs

@@ -9,6 +9,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:pat
 import { fileURLToPath } from "node:url";
 import { readProjectFile } from "./project.mjs";
 import { record } from "./spool.mjs";
+import { trackTurn } from "./turns.mjs";
 import { taskFrom, taskMode } from "./tasks.mjs";
 
 const EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Notification", "Stop", "SessionEnd"];
@@ -114,6 +115,8 @@ export async function runHook() {
       if (task) Object.assign(status, task);
       const file = fileFrom(input, mode);
       if (file) Object.assign(status, file);
+      const turn = trackTurn(input, status.session);
+      if (turn) status.turn = turn; // the finished turn's size: three numbers
       record(status);
     }
   } catch { /* a monitoring hook must never break the agent */ }
@@ -121,7 +124,7 @@ export async function runHook() {
 }
 
 // ── install / uninstall ─────────────────────────────────────────
-function settingsPath(cwd) {
+export function settingsPath(cwd) {
   let d = resolve(cwd);
   for (let i = 0; i < 20; i++) {
     if (existsSync(join(d, ".git"))) break;
@@ -134,7 +137,7 @@ function settingsPath(cwd) {
 
 // Reads the settings file, or explains (and changes nothing) when it isn't valid JSON — often two
 // { … } blocks pasted one after the other, which Claude Code can't read either.
-function readSettings(file) {
+export function readSettings(file) {
   if (!existsSync(file)) return {};
   const text = readFileSync(file, "utf8");
   try {
@@ -151,6 +154,12 @@ function readSettings(file) {
   return null;
 }
 
+export function writeSettings(file, settings) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}
+`);
+}
+
 export function install(cwd = process.cwd()) {
   const file = settingsPath(cwd);
   const settings = readSettings(file);

package/src/spool.mjs

@@ -72,6 +72,7 @@ export function aggregate(events) {
     if (e.exit_code !== undefined && e.exit_code !== null) cur.exit_code = e.exit_code;
     if (e.ended) cur.ended = true;
     if (e.transcript) cur.transcript = e.transcript;
+    if (e.turn) cur.turn = e.turn;
     if (e.started_at && e.started_at < cur.started_at) cur.started_at = e.started_at;
     if (typeof e.task === "string") {
       Object.assign(cur, { task: e.task, task_source: e.task_source, task_done: e.task_done ?? 0, task_total: e.task_total ?? 0, task_at: e.at });

package/src/statusline.mjs

@@ -0,0 +1,135 @@
+// Claude plan limits on the M.E.K.S.U.S. dashboard (Rik, 2026-09-26).
+//   `meksus statusline`   Claude Code's status line command. Reads the status line JSON on stdin and
+//                         prints one short line ("5h 23% · resets in 2h 14m │ week 41% · Tue 09:00").
+//                         Keeps ONLY rate_limits (percentages + reset times) in ~/.meksus/limits.json and,
+//                         when they changed (or every 5 minutes), starts a detached `meksus limits-flush`,
+//                         at most once a minute (G-1). Never blocks, never breaks the status line.
+//   `meksus statusline install [--global] [--replace]` / `uninstall [--global]`
+//                         <repo>/.claude/settings.local.json, or ~/.claude/settings.json with --global.
+//   `meksus limits-flush` internal, detached: one POST /v1/claude-limits as the signed-in user.
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAccessToken } from "./auth.mjs";
+import { apiBase, dir, ensureDir, readConfig } from "./config.mjs";
+import { readSettings, settingsPath, writeSettings } from "./hooks.mjs";
+import { VERSION } from "./version.mjs";
+
+const CLI = fileURLToPath(new URL("../bin/meksus.mjs", import.meta.url));
+const MARK = "meksus.mjs\" statusline";
+const WINDOWS = ["five_hour", "seven_day", "spend_limit"];
+export const SEND_MIN_MS = 60_000;
+export const SEND_EVERY_MS = 5 * 60_000;
+const limitsFile = () => join(dir(), "limits.json");
+
+/** Only the numbers: { five_hour: { used_percentage, resets_at }, … }, or null. */
+export function pickLimits(input) {
+  const src = input?.rate_limits;
+  if (!src || typeof src !== "object") return null;
+  const out = {};
+  for (const w of WINDOWS) {
+    const v = src[w];
+    const pct = Number(v?.used_percentage);
+    const at = Number(v?.resets_at);
+    if (Number.isFinite(pct) && Number.isFinite(at)) out[w] = { used_percentage: Math.round(pct * 100) / 100, resets_at: Math.round(at) };
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+export function until(resetsAtS, nowMs = Date.now()) {
+  const s = Math.max(0, Math.round(resetsAtS - nowMs / 1000));
+  const d = Math.floor(s / 86400), hh = Math.floor((s % 86400) / 3600), mm = Math.floor((s % 3600) / 60);
+  return d ? `${d}d ${hh}h` : hh ? `${hh}h ${String(mm).padStart(2, "0")}m` : `${mm}m`;
+}
+
+export function renderLine(limits, nowMs = Date.now()) {
+  if (!limits) return "Claude limits: after the first reply";
+  const part = (label, w) => (w ? `${label} ${Math.round(w.used_percentage)}% · resets in ${until(w.resets_at, nowMs)}` : null);
+  return [part("5h", limits.five_hour), part("week", limits.seven_day), part("spend", limits.spend_limit)].filter(Boolean).join(" │ ");
+}
+
+const signature = (l) => JSON.stringify(WINDOWS.map((w) => (l?.[w] ? [Math.round(l[w].used_percentage), l[w].resets_at] : null)));
+
+/** Should this run start a send? (changed and a minute since the last one, or 5 minutes regardless) */
+export function sendDue(state, limits, nowMs = Date.now()) {
+  if (!limits) return false;
+  const since = nowMs - (state?.sent_at ?? 0);
+  return (signature(limits) !== state?.sent_sig && since >= SEND_MIN_MS) || since >= SEND_EVERY_MS;
+}
+
+function readState() { try { return JSON.parse(readFileSync(limitsFile(), "utf8")); } catch { return null; } }
+function writeState(s) { try { ensureDir(); writeFileSync(limitsFile(), JSON.stringify(s)); } catch { /* read-only home: just don't send */ } }
+
+export async function runStatusline() {
+  let limits = null;
+  try {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    limits = pickLimits(JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}"));
+  } catch { /* bad input: still print something */ }
+  const state = readState();
+  const shown = limits ?? state?.limits ?? null;
+  process.stdout.write(`${renderLine(shown)}\n`);
+  if (limits && sendDue(state, limits) && readConfig()?.session) {
+    writeState({ limits, at: Date.now(), sent_at: Date.now(), sent_sig: signature(limits) }); // claim before spawning
+    try { spawn(process.execPath, [CLI, "limits-flush"], { detached: true, stdio: "ignore", windowsHide: true, env: process.env }).unref(); } catch { /* next run */ }
+  } else if (limits) {
+    writeState({ ...(state ?? {}), limits, at: Date.now() });
+  }
+  return 0;
+}
+
+export async function limitsFlush() {
+  const state = readState();
+  const config = readConfig();
+  if (!state?.limits || !config?.session) return 0;
+  const token = await getAccessToken(config);
+  if (!token) return 0;
+  try {
+    const res = await fetch(`${apiBase(config)}/v1/claude-limits`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "User-Agent": `meksus-cli/${VERSION}`, Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ rate_limits: state.limits }),
+      signal: AbortSignal.timeout(8000),
+    });
+    await res.body?.cancel();
+    return res.status;
+  } catch { return 0; } // dropped; the next status line run sends again (G-11)
+}
+
+// ── install / uninstall ─────────────────────────────────────────
+const globalSettings = () => join(homedir(), ".claude", "settings.json");
+
+export function statuslineCommand(args) {
+  const global = args.includes("--global");
+  const file = global ? globalSettings() : settingsPath(process.cwd());
+  if (args[0] === "install") {
+    const settings = readSettings(file);
+    if (!settings) return 1;
+    const current = settings.statusLine?.command ?? "";
+    if (current && !current.includes(MARK) && !args.includes("--replace")) {
+      console.error(`✖ ${file} already has a status line: ${current}`);
+      console.error("  Run again with --replace to use the M.E.K.S.U.S. one instead (it shows your Claude plan limits).");
+      return 1;
+    }
+    settings.statusLine = { type: "command", command: `node "${CLI}" statusline`, padding: 0, refreshInterval: 30 };
+    writeSettings(file, settings);
+    console.log(`✔ Status line installed in ${file}`);
+    console.log("  It shows your Claude plan limits (5-hour and weekly) and sends only those numbers to your M.E.K.S.U.S. dashboard, at most once a minute.");
+    console.log("  Claude Code provides them for claude.ai Pro and Max plans, after the first reply in a session.");
+    return 0;
+  }
+  if (args[0] === "uninstall") {
+    const settings = readSettings(file);
+    if (!settings) return 1;
+    if (!String(settings.statusLine?.command ?? "").includes(MARK)) { console.log(`No M.E.K.S.U.S. status line in ${file}.`); return 0; }
+    delete settings.statusLine;
+    writeSettings(file, settings);
+    console.log(`✔ Status line removed from ${file}`);
+    return 0;
+  }
+  console.error("Usage: meksus statusline install [--global] [--replace] | uninstall [--global]");
+  return 2;
+}

package/src/turns.mjs

@@ -0,0 +1,41 @@
+// How big was the turn Claude just finished? Measured here, on this machine, from the hooks themselves:
+// the time from the prompt (UserPromptSubmit) to Stop, the tool calls in between, and how many distinct
+// files it changed (Edit / Write / MultiEdit / NotebookEdit). Only those three numbers are sent, with the
+// Stop event; file names are kept locally as hashes, only to count them once, and dropped with the turn.
+// The server scores big vs small (packages/shared/src/notices.ts taskSize) for the AI-coder notices.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dir, ensureDir } from "./config.mjs";
+
+const EDITS = new Set(["Edit", "MultiEdit", "Write", "NotebookEdit"]);
+const KEEP = 50; // sessions remembered at most
+const file = () => join(dir(), "turns.json");
+
+function load() { try { return JSON.parse(readFileSync(file(), "utf8")); } catch { return {}; } }
+function save(turns) {
+  const entries = Object.entries(turns).sort((a, b) => (b[1].at ?? 0) - (a[1].at ?? 0)).slice(0, KEEP);
+  try { ensureDir(); writeFileSync(file(), JSON.stringify(Object.fromEntries(entries))); } catch { /* not measured, not fatal */ }
+}
+
+/** Updates the session's running turn; on Stop returns { seconds, tool_calls, files }, else null. */
+export function trackTurn(input, session, now = Date.now()) {
+  const name = input?.hook_event_name;
+  if (!session || !["UserPromptSubmit", "PreToolUse", "Stop"].includes(name)) return null;
+  const turns = load();
+  let t = turns[session];
+  if (name === "UserPromptSubmit" || !t) t = { start: now, tools: 0, files: [], at: now };
+  if (name === "PreToolUse") {
+    t.tools += 1;
+    const target = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
+    if (EDITS.has(input.tool_name) && typeof target === "string") {
+      const h = createHash("sha256").update(target).digest("hex").slice(0, 16);
+      if (!t.files.includes(h) && t.files.length < 500) t.files.push(h);
+    }
+  }
+  t.at = now;
+  turns[session] = t;
+  save(turns);
+  if (name !== "Stop") return null;
+  return { seconds: Math.max(0, Math.round((now - t.start) / 1000)), tool_calls: t.tools, files: t.files.length };
+}