meksus 0.4.0 → 0.6.0

package/README.md

@@ -29,12 +29,23 @@ The project's exact `<owner/project>` name is shown on its page in the dashboard
 
 ```sh
 meksus hooks install                          # in the repo: adds Claude Code hooks to .claude/settings.local.json
+meksus hooks install --codex                  # Codex: once per computer (~/.codex/hooks.json)
 meksus task-lines steps                       # optional: show the step Claude is on, in one line
 meksus watch --label "build" -- npm run build # any command; a failure opens an incident and alerts Discord
 ```
 
 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)
+```
+
+Then **start Claude Code in a terminal** (`claude`; in VS Code: Terminal → New Terminal) and send it one message. The VS Code chat panel doesn't draw a status line, so it can't pass the numbers on. The bottom of the terminal 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 within a minute. 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.
+
+Not showing up? `meksus statusline doctor` checks every step and says which one is missing.
+
 ## Check
 
 ```sh
@@ -53,6 +64,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 |
@@ -64,7 +79,9 @@ The server scrubs anything that looks like a secret.
 | `meksus project create <name> [--in <parent>] [--use]` | Create a project (owners and admins) |
 | `meksus project use <owner/project>` | Write this repo's `.meksus` |
 | `meksus hooks install` / `uninstall` | Watch Claude Code in this repo |
+| `meksus hooks install --codex` / `uninstall --codex` | Watch Codex on this computer (repositories with a `.meksus` file) |
 | `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";
@@ -21,7 +22,11 @@ const HELP = `M.E.K.S.U.S. CLI ${VERSION}
   meksus project create <name> [--in <parent>] [--slug <slug>] [--use]
   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 hooks install --codex | uninstall --codex  Watch Codex (once per computer; repos with .meksus)
   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 statusline doctor                        Check the plan-limits setup step by step
   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
@@ -42,12 +47,16 @@ switch (command) {
   case "resolve": code = await incidentCommand("resolve", rest[0]); break;
   case "project": case "projects": code = (await requireAccess()) ? await projectCommand(rest) : 1; break;
   case "hooks":
-    if (rest[0] === "install") code = (await requireAccess()) ? install() : 1;
-    else if (rest[0] === "uninstall") code = uninstall();
-    else { console.error("Usage: meksus hooks install | uninstall"); code = 2; }
+    if (rest[0] === "install") code = (await requireAccess()) ? install(process.cwd(), { codex: flag("--codex") }) : 1;
+    else if (rest[0] === "uninstall") code = uninstall(process.cwd(), { codex: flag("--codex") });
+    else { console.error("Usage: meksus hooks install | uninstall [--codex]"); code = 2; }
     break;
-  case "hook": code = await runHook(); break; // called by Claude Code, silent
+  case "hook": code = await runHook(rest[0] === "--agent" && rest[1] === "codex" ? "codex" : "claude-code"); break; // called by the agent, silent
   case "task-lines": code = taskLinesCommand(rest); break;
+  case "statusline":
+    code = rest.length ? ((rest[0] === "install" && !(await requireAccess())) ? 1 : await 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.6.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

@@ -1,17 +1,23 @@
-// Claude Code integration.
-//   `meksus hook`            the hook command itself: reads the hook JSON on stdin, records a status
-//                            line, exits 0 and prints NOTHING (some hooks feed stdout back to Claude).
+// Claude Code and Codex integration.
+//   `meksus hook [--agent codex]`  the hook command itself: reads the hook JSON on stdin, records a status
+//                            line, exits 0 and prints NOTHING (some hooks feed stdout back to the agent).
 //   `meksus hooks install`   adds the hook to <repo>/.claude/settings.local.json (personal, gitignored)
-//   `meksus hooks uninstall` removes only our entries
+//   `meksus hooks install --codex`  adds it to ~/.codex/hooks.json (Codex's own hooks, same shape; once per
+//                            computer: repositories without a .meksus file are never reported)
+//   `meksus hooks uninstall [--codex]` removes only our entries
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 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"];
+// Codex (learn.chatgpt.com/docs/hooks): the same events, "PermissionRequest" instead of "Notification".
+const CODEX_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "SessionEnd"];
 const TOOL_EVENTS = new Set(["PreToolUse", "PostToolUse"]);
 const CLI = fileURLToPath(new URL("../bin/meksus.mjs", import.meta.url));
 const MARK = "meksus.mjs\" hook";
@@ -21,7 +27,7 @@ export function sessionKey(agent, id) {
 }
 
 /** Maps one Claude Code hook payload to a status line (or null to ignore). Exported for tests. */
-export function toStatus(input, now = new Date()) {
+export function toStatus(input, now = new Date(), agent = "claude-code") {
   const name = input?.hook_event_name;
   if (!name || !input.session_id) return null;
   // PRJ-10/13: status belongs to the project named by the repo's .meksus file; no file → not reported.
@@ -29,11 +35,13 @@ export function toStatus(input, now = new Date()) {
   if (!project) return null;
   const e = {
     project,
-    session: sessionKey("claude-code", input.session_id),
-    agent: "claude-code",
+    session: sessionKey(agent, input.session_id),
+    agent,
     label: repoLabel(input.cwd),
     at: now.toISOString(),
-    transcript: typeof input.transcript_path === "string" ? input.transcript_path : null,
+    // Token usage is read from Claude Code's transcript format; Codex reports its model name instead.
+    transcript: agent === "claude-code" && typeof input.transcript_path === "string" ? input.transcript_path : null,
+    ...(agent === "codex" && typeof input.model === "string" && /^[a-z0-9][a-z0-9.\-]{0,62}$/.test(input.model) ? { model: input.model } : {}),
   };
   switch (name) {
     case "SessionStart": return { ...e, state: "idle", started_at: e.at };
@@ -42,6 +50,7 @@ export function toStatus(input, now = new Date()) {
     case "PostToolUse": return { ...e, state: "working", tool_failure: toolFailed(input.tool_response) };
     case "PostToolUseFailure": return { ...e, state: "working", tool_failure: true };
     case "Notification": return { ...e, state: "waiting" };
+    case "PermissionRequest": return { ...e, state: "waiting" }; // Codex asks before running something
     case "Stop": return { ...e, state: "finished" };
     case "SessionEnd": return { ...e, state: "finished", ended: true };
     default: return null;
@@ -101,12 +110,12 @@ export function repoLabel(cwd) {
   return basename(root).slice(0, 80);
 }
 
-export async function runHook() {
+export async function runHook(agent = "claude-code") {
   try {
     const chunks = [];
     for await (const c of process.stdin) chunks.push(c);
     const input = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
-    const status = toStatus(input);
+    const status = toStatus(input, new Date(), agent);
     if (status) {
       // Opt-in one-line "working on" from the agent's own step list (`meksus task-lines`).
       const mode = taskMode();
@@ -114,6 +123,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 +132,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 +145,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,18 +162,36 @@ function readSettings(file) {
   return null;
 }
 
-export function install(cwd = process.cwd()) {
-  const file = settingsPath(cwd);
+export function writeSettings(file, settings) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}
+`);
+}
+
+export const codexHooksPath = () => join(homedir(), ".codex", "hooks.json");
+
+export function install(cwd = process.cwd(), { codex = false } = {}) {
+  const file = codex ? codexHooksPath() : settingsPath(cwd);
   const settings = readSettings(file);
   if (!settings) return 1;
   settings.hooks ??= {};
-  const command = `node "${CLI}" hook`;
-  for (const event of EVENTS) {
+  const command = codex ? `node "${CLI}" hook --agent codex` : `node "${CLI}" hook`;
+  for (const event of codex ? CODEX_EVENTS : EVENTS) {
     const groups = (settings.hooks[event] ??= []);
     const clean = groups.map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !String(h.command).includes(MARK)) })).filter((g) => g.hooks.length);
-    clean.push({ ...(TOOL_EVENTS.has(event) ? { matcher: "*" } : {}), hooks: [{ type: "command", command, timeout: 10 }] });
+    // Claude Code's tool matcher "*" means every tool; Codex matchers are regexes, so none = every tool.
+    clean.push({ ...(TOOL_EVENTS.has(event) && !codex ? { matcher: "*" } : {}), hooks: [{ type: "command", command, timeout: 10 }] });
     settings.hooks[event] = clean;
   }
+  if (codex) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+    console.log(`✔ Codex hooks installed in ${file}`);
+    console.log("  Every Codex session in a repository with a .meksus file now reports: working, needs you, finished.");
+    console.log("  Sent: state, timings, tool-call counts and the model name. Never code, prompts or output.");
+    console.log("  Start a new Codex session to activate. Hooks are on by default in Codex ([features] hooks).");
+    return 0;
+  }
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
   console.log(`✔ Claude Code hooks installed in ${file}`);
@@ -172,8 +201,8 @@ export function install(cwd = process.cwd()) {
   return 0;
 }
 
-export function uninstall(cwd = process.cwd()) {
-  const file = settingsPath(cwd);
+export function uninstall(cwd = process.cwd(), { codex = false } = {}) {
+  const file = codex ? codexHooksPath() : settingsPath(cwd);
   if (!existsSync(file)) { console.log("No hooks file here."); return 0; }
   const settings = readSettings(file);
   if (!settings) return 1;

package/src/spool.mjs

@@ -72,6 +72,8 @@ 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.model) cur.model = e.model; // Codex names its model in every hook call
     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,218 @@
+// 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, with
+//                         WHEN each Claude Code session last got them from Anthropic (observed_at). Only the
+//                         newest reading on this computer is sent, with that time, so an idle session's old
+//                         numbers never overwrite a newer reading (the server keeps the newest too).
+//                         Sends: numbers changed → at most once a minute; same numbers re-confirmed by newer
+//                         activity → at most every 5 minutes; nothing new → nothing sent (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.
+//   `meksus statusline doctor`  checks every step (CLI, sign-in, access, the setting, whether Claude Code
+//                         ran the status line and gave plan limits, the last send) and says what's missing.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync, 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 { hasAccess } from "./access.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");
+const seenFile = () => join(dir(), "statusline-seen.json"); // when Claude Code last ran us, and with what (no numbers)
+function readSeen() { try { return JSON.parse(readFileSync(seenFile(), "utf8")); } catch { return {}; } }
+function writeSeen(patch) { try { ensureDir(); writeFileSync(seenFile(), JSON.stringify({ ...readSeen(), ...patch })); } catch { /* diagnostics only */ } }
+
+/** 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(" │ ");
+}
+
+export const signature = (l) => JSON.stringify(WINDOWS.map((w) => (l?.[w] ? [Math.round(l[w].used_percentage), l[w].resets_at] : null)));
+const SESSIONS_MAX = 20;
+const SESSION_TTL_MS = 24 * 3600_000;
+
+/**
+ * Records one status line run. Claude Code hands every session its own last rate_limits (from that session's
+ * last API response) and re-runs the status line every 30 s even when idle, so the numbers alone don't say
+ * how old they are. Per session: first sight → the transcript's last write (≈ the last reply); numbers
+ * changed → now (a reply just arrived); same numbers → re-confirmed at the transcript's last write.
+ * The state's reading is the newest across this computer's sessions.
+ */
+export function observe(state, sessionId, limits, transcriptMs, nowMs = Date.now()) {
+  const next = { ...(state ?? {}), sessions: { ...(state?.sessions ?? {}) } };
+  if (!limits) return next;
+  const sid = String(sessionId ?? "unknown").slice(0, 64);
+  const sig = signature(limits);
+  const mt = Number.isFinite(transcriptMs) ? Math.min(transcriptMs, nowMs) : null;
+  const prev = next.sessions[sid];
+  const obs = !prev ? (mt ?? nowMs) : prev.sig !== sig ? nowMs : Math.max(prev.obs, mt ?? prev.obs);
+  next.sessions[sid] = { sig, obs, seen: nowMs };
+  for (const [k, v] of Object.entries(next.sessions)) if (nowMs - (v.seen ?? 0) > SESSION_TTL_MS) delete next.sessions[k];
+  const keep = Object.entries(next.sessions).sort((a, b) => b[1].seen - a[1].seen).slice(0, SESSIONS_MAX);
+  next.sessions = Object.fromEntries(keep);
+  if (!next.observed_at || obs >= next.observed_at) { next.limits = limits; next.observed_at = obs; next.sig = sig; }
+  return next;
+}
+
+/** Should this run start a send? New numbers: a minute since the last try. Same numbers seen again later: 5 minutes. */
+export function sendDue(state, nowMs = Date.now()) {
+  if (!state?.limits || !state.observed_at) return false;
+  if (state.observed_at <= (state.sent_obs ?? 0)) return false; // nothing newer than what the server has
+  const since = nowMs - (state.tried_at ?? 0);
+  return state.sig !== 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 */ } }
+function mtimeMs(path) { try { return typeof path === "string" && path ? statSync(path).mtimeMs : null; } catch { return null; } }
+
+export async function runStatusline() {
+  let limits = null;
+  let claude = null;
+  let sessionId = null;
+  let transcript = null;
+  try {
+    const chunks = [];
+    for await (const c of process.stdin) chunks.push(c);
+    const input = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    limits = pickLimits(input);
+    claude = typeof input.version === "string" ? input.version.slice(0, 20) : null;
+    sessionId = input.session_id ?? null;
+    transcript = input.transcript_path ?? null;
+  } catch { /* bad input: still print something */ }
+  writeSeen({ last_run: Date.now(), had_limits: Boolean(limits), claude_version: claude, ...(limits ? { last_limits: Date.now() } : {}) });
+  const state = readState();
+  process.stdout.write(`${renderLine(limits ?? state?.limits ?? null)}\n`);
+  if (!limits) return 0;
+  const next = observe(state, sessionId, limits, mtimeMs(transcript));
+  if (sendDue(next) && readConfig()?.session) {
+    writeState({ ...next, tried_at: Date.now() }); // claim before spawning
+    try { spawn(process.execPath, [CLI, "limits-flush"], { detached: true, stdio: "ignore", windowsHide: true, env: process.env }).unref(); } catch { /* next run */ }
+  } else {
+    writeState(next);
+  }
+  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;
+  const sent = { limits: state.limits, observed_at: state.observed_at ?? Date.now(), sig: state.sig ?? signature(state.limits) };
+  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: sent.limits, observed_at: sent.observed_at }),
+      signal: AbortSignal.timeout(8000),
+    });
+    await res.body?.cancel();
+    writeSeen({ sent_at: Date.now(), sent_status: res.status });
+    if (res.ok) { const now = readState() ?? state; writeState({ ...now, sent_obs: Math.max(now.sent_obs ?? 0, sent.observed_at), sent_sig: sent.sig }); }
+    return res.status;
+  } catch { writeSeen({ sent_at: Date.now(), sent_status: 0 }); 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;
+  }
+  if (args[0] === "doctor") return doctor();
+  console.error("Usage: meksus statusline install [--global] [--replace] | uninstall [--global] | doctor");
+  return 2;
+}
+
+const ago = (ms) => { const s = Math.round((Date.now() - ms) / 1000); return s < 90 ? `${s} s ago` : s < 5400 ? `${Math.round(s / 60)} min ago` : s < 172800 ? `${Math.round(s / 3600)} h ago` : `${Math.round(s / 86400)} days ago`; };
+
+/** Walks the whole path and stops at the first missing step, in plain words. */
+async function doctor() {
+  const ok = (t) => console.log(`✔ ${t}`);
+  const bad = (t, fix) => { console.log(`✖ ${t}`); if (fix) console.log(`  → ${fix}`); return 1; };
+  ok(`meksus ${VERSION}`);
+  const config = readConfig();
+  if (!config?.session) return bad("Not signed in to M.E.K.S.U.S. on this computer.", "Run: meksus login");
+  ok(`Signed in as ${config.user?.name ?? config.user?.email ?? "you"}`);
+  const access = await hasAccess({ fresh: true });
+  if (access === false) return bad("This account has no access to M.E.K.S.U.S. (private preview).", "Ask your team's admin to invite you.");
+  if (access === true) ok("Access: yes");
+  const places = [globalSettings(), settingsPath(process.cwd())].filter((f, i, a) => a.indexOf(f) === i);
+  const installed = places.find((f) => { try { return existsSync(f) && String(JSON.parse(readFileSync(f, "utf8")).statusLine?.command ?? "").includes(MARK); } catch { return false; } });
+  if (!installed) return bad("Claude Code's status line isn't set to meksus.", "Run: meksus statusline install --global   (then start a new Claude Code session)");
+  ok(`Status line set in ${installed}`);
+  const seen = readSeen();
+  if (!seen.last_run) return bad("Claude Code hasn't run the status line on this computer yet.",
+    "Start Claude Code in a terminal (type: claude) and send it one message. The VS Code chat panel doesn't draw a status line; use a terminal, e.g. VS Code's Terminal → New Terminal.");
+  ok(`Claude Code last ran it ${ago(seen.last_run)}${seen.claude_version ? ` (Claude Code ${seen.claude_version})` : ""}`);
+  if (!seen.last_limits) return bad("Claude Code hasn't included plan limits yet.",
+    "Send Claude a message in that terminal session. If you signed in to Claude Code with an API key instead of a Pro or Max plan, there are no plan limits to show.");
+  ok(`Plan limits last seen ${ago(seen.last_limits)}`);
+  if (!seen.sent_at) return bad("Not sent to M.E.K.S.U.S. yet.", "It sends within a minute of the next reply. Run this again in a minute.");
+  if (seen.sent_status < 200 || seen.sent_status >= 300) {
+    return bad(`The last send failed (${seen.sent_status ? `HTTP ${seen.sent_status}` : "no connection"}, ${ago(seen.sent_at)}).`,
+      seen.sent_status === 401 ? "Sign in again: meksus login" : seen.sent_status === 403 ? "This account has no access (private preview)." : "It retries with the next reply. Check your connection.");
+  }
+  ok(`Sent to M.E.K.S.U.S. ${ago(seen.sent_at)}. Open the dashboard → Agents: the Claude plan limits card is live.`);
+  return 0;
+}

package/src/turns.mjs

@@ -0,0 +1,52 @@
+// 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"]);
+
+/** Files a tool call changes: Claude Code's edit tools name one file_path; Codex's apply_patch lists them
+ *  in the patch ("*** Update File: src/a.js"). Paths only, used here and never sent. */
+export function editedFiles(input) {
+  const target = input?.tool_input?.file_path ?? input?.tool_input?.notebook_path;
+  if (EDITS.has(input?.tool_name) && typeof target === "string") return [target];
+  if (/apply_patch/i.test(String(input?.tool_name ?? ""))) {
+    const text = Object.values(input.tool_input ?? {}).filter((v) => typeof v === "string").join("\n");
+    return [...text.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)].map((m) => m[1].trim()).slice(0, 200);
+  }
+  return [];
+}
+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;
+    for (const target of editedFiles(input)) {
+      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 };
+}