@echomem/mcp 1.4.7 → 1.4.9

package/dist/hud/adapters.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveClaudeProjectsDir, resolveCodexSessionsDir } from "../local-data-paths.js";
 import { homePath, newestFile, readJsonl, walkFiles } from "./fs.js";
 import { bumpTurn, newMetricState, recordEdit, recordRead, recordTool, scoreMetric, shellRead, } from "./metric.js";
 export const adapters = {
@@ -31,8 +32,8 @@ export function adapterList(mode) {
     return [adapters[mode]];
 }
 function listCodex() {
-    const root = process.env.CODEX_HOME ? path.join(process.env.CODEX_HOME, "sessions") : homePath(".codex", "sessions");
-    return walkFiles(root, (file) => /^rollout-.*\.jsonl$/.test(path.basename(file)));
+    const root = resolveCodexSessionsDir();
+    return root ? walkFiles(root, (file) => /^rollout-.*\.jsonl$/.test(path.basename(file))) : [];
 }
 function findActiveCodex() {
     return newestFile(listCodex());
@@ -121,10 +122,13 @@ function scoreCodex(file) {
     return score;
 }
 function listClaudeCode() {
-    return walkFiles(homePath(".claude", "projects"), (file) => file.endsWith(".jsonl"));
+    const root = resolveClaudeProjectsDir();
+    return root ? walkFiles(root, (file) => file.endsWith(".jsonl")) : [];
 }
 function findActiveClaudeCode() {
-    const cache = newestFile(walkFiles(homePath(".claude", "echo-ctx"), (file) => file.endsWith(".json")));
+    const projects = resolveClaudeProjectsDir();
+    const cacheRoot = projects ? path.join(path.dirname(projects), "echo-ctx") : null;
+    const cache = cacheRoot ? newestFile(walkFiles(cacheRoot, (file) => file.endsWith(".json"))) : null;
     if (cache)
         return cache;
     return newestFile(listClaudeCode());

package/dist/hud/autostart.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+// Show-after-restart for the HUD via a macOS LaunchAgent. We ship a CLI, not an .app bundle, so this is
+// the standard way to make the overlay persist across quit/reboot. Shared by the CLI (`echomem-hud
+// autostart`) and the Electron context menu so both write an identical, robust registration.
+const LABEL = "com.echomem.hud";
+export function autostartPlistPath() {
+    return path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+export function autostartSupported() {
+    return process.platform === "darwin";
+}
+export function isAutostartEnabled() {
+    return autostartSupported() && fs.existsSync(autostartPlistPath());
+}
+function escapeXml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function launchctlUid() {
+    return typeof process.getuid === "function" ? process.getuid() : 501;
+}
+/**
+ * Register the LaunchAgent. `programArgs` is the full ProgramArguments array — the caller supplies the
+ * exact launch command (electron binary + electron-main.js + flags) so it works regardless of whether
+ * node is on launchd's PATH. Loads immediately as well as at future logins.
+ */
+export function enableAutostart(programArgs) {
+    if (!autostartSupported())
+        return { ok: false, message: "autostart is currently macOS-only." };
+    const plist = autostartPlistPath();
+    const argsXml = programArgs.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array>
+${argsXml}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>/tmp/echomem-hud.log</string>
+  <key>StandardErrorPath</key><string>/tmp/echomem-hud.log</string>
+</dict></plist>
+`;
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist, xml);
+    const uid = launchctlUid();
+    spawnSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" }); // replace stale reg
+    const boot = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, plist], { encoding: "utf8" });
+    return boot.status === 0
+        ? { ok: true, message: `EchoMem HUD will show after restart. Off anytime: echomem-hud autostart off` }
+        : { ok: true, message: `Wrote ${plist} — shows after your next restart.` };
+}
+export function disableAutostart() {
+    if (!autostartSupported())
+        return;
+    const uid = launchctlUid();
+    spawnSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" });
+    try {
+        fs.rmSync(autostartPlistPath(), { force: true });
+    }
+    catch {
+        /* already gone */
+    }
+}

package/dist/hud/cli.js

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { adapterList } from "./adapters.js";
+import { autostartPlistPath, autostartSupported, disableAutostart, enableAutostart, isAutostartEnabled } from "./autostart.js";
 import { statSignature } from "./fs.js";
 import { installHooks } from "./hooks.js";
 import { HudMonitor } from "./monitor.js";
@@ -23,6 +24,8 @@ try {
         await cmdApp(flags);
     else if (command === "install-hooks")
         await cmdInstallHooks(flags);
+    else if (command === "autostart")
+        cmdAutostart(argv[1] || "status", flags);
     else if (command === "status")
         await cmdStatus(flags);
     else if (command === "report")
@@ -79,6 +82,33 @@ async function cmdApp(flags) {
     child.unref();
     console.log("EchoMem HUD app launched.");
 }
+/**
+ * `echomem-hud autostart on|off|status` — show the HUD after restart via a macOS LaunchAgent, so
+ * closing/rebooting doesn't lose it (we ship a CLI, not an .app, so this is the standard mechanism).
+ * The registration runs the electron binary directly on electron-main.js — no dependency on node
+ * being on launchd's PATH — matching what the in-app "Show after restart" toggle writes.
+ */
+function cmdAutostart(action, flags) {
+    if (!autostartSupported()) {
+        console.log("autostart is currently macOS-only (LaunchAgent).");
+        return;
+    }
+    if (action === "on") {
+        const require = createRequire(import.meta.url);
+        const electronPath = require("electron");
+        const mainPath = fileURLToPath(new URL("./electron-main.js", import.meta.url));
+        const client = typeof flags.client === "string" ? flags.client : "auto";
+        const result = enableAutostart([electronPath, mainPath, "--client", client]);
+        console.log(`✅ ${result.message}`);
+        return;
+    }
+    if (action === "off") {
+        disableAutostart();
+        console.log("✅ Show after restart disabled — the HUD will not relaunch after restart.");
+        return;
+    }
+    console.log(isAutostartEnabled() ? `Autostart: ON (${autostartPlistPath()})` : "Autostart: OFF. Enable with: echomem-hud autostart on");
+}
 async function cmdInstallHooks(flags) {
     const paths = installHooks(parseMode(flags.client));
     console.log(`Installed EchoMem HUD hook support:\n${paths.map((p) => `- ${p}`).join("\n")}`);
@@ -136,6 +166,7 @@ Usage:
   echomem-hud serve [--client codex|claude-code|claude-desktop|both|auto] [--port 17377]
   echomem-hud app [--client codex|claude-code|claude-desktop|both|auto]
   echomem-hud install-hooks [--client codex|claude-code|both]
+  echomem-hud autostart on|off|status   (show the HUD after restart — macOS)
   echomem-hud status
   echomem-hud report [--client codex|claude-code|claude-desktop|auto] [--limit 40] [--json]
 `);

package/dist/hud/electron-main.js

@@ -1,8 +1,10 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { app, BrowserWindow, ipcMain, Menu, screen, shell } from "electron";
+import { app, BrowserWindow, dialog, ipcMain, Menu, nativeImage, screen, shell } from "electron";
+import { disableAutostart, enableAutostart, isAutostartEnabled } from "./autostart.js";
 import { createHudServer } from "./server.js";
 const flags = parseFlags(process.argv.slice(2));
 const mode = parseMode(flags.client);
@@ -10,8 +12,16 @@ const port = typeof flags.port === "string" ? Number(flags.port) || 17377 : 1737
 const COLLAPSED_WIDTH = 360;
 const COLLAPSED_HEIGHT = 112;
 const EXPANDED_HEIGHT = 460;
+// Mini mode: a small always-on pill (status dot + tokens) for users who find the full bubble too big.
+const MINI_WIDTH = 190;
+const MINI_HEIGHT = 48;
+const AGENT_VISIBILITY_POLL_MS = 900;
+let miniPref = false;
+let onlyShowWhenAgentOpen = false;
+let manuallyHidden = false;
 let hudServer = null;
 let mainWindow = null;
+let visibilityTimer = null;
 const dragState = new Map();
 // Single-instance: a second `echomem-hud app` brings the existing HUD back instead of opening another.
 const gotSingleInstanceLock = app.requestSingleInstanceLock();
@@ -28,8 +38,23 @@ app.whenReady().then(async () => {
         if (!win)
             return;
         const bounds = win.getBounds();
-        const height = open ? clampExpandedHeight(measured && measured > 200 ? measured : EXPANDED_HEIGHT) : COLLAPSED_HEIGHT;
-        win.setBounds({ ...bounds, height });
+        // Closing returns to the user's preferred resting size (mini pill or the full bubble).
+        const width = open ? COLLAPSED_WIDTH : miniPref ? MINI_WIDTH : COLLAPSED_WIDTH;
+        const height = open ? clampExpandedHeight(measured && measured > 200 ? measured : EXPANDED_HEIGHT) : miniPref ? MINI_HEIGHT : COLLAPSED_HEIGHT;
+        win.setBounds({ ...bounds, width, height });
+        writeBounds(win);
+    });
+    ipcMain.on("hud:set-mini", (event, payload) => {
+        miniPref = typeof payload === "object" ? Boolean(payload.mini) : Boolean(payload);
+        const win = BrowserWindow.fromWebContents(event.sender);
+        if (!win)
+            return;
+        const bounds = win.getBounds();
+        win.setBounds({
+            ...bounds,
+            width: miniPref ? MINI_WIDTH : COLLAPSED_WIDTH,
+            height: miniPref ? MINI_HEIGHT : COLLAPSED_HEIGHT,
+        });
         writeBounds(win);
     });
     ipcMain.on("hud:drag-start", (event, payload) => {
@@ -99,10 +124,12 @@ app.on("window-all-closed", async () => {
 });
 function createWindow(url) {
     const savedBounds = readBounds();
+    miniPref = Boolean(savedBounds?.mini);
+    onlyShowWhenAgentOpen = Boolean(savedBounds?.onlyShowWhenAgentOpen);
     const bounds = savedBounds ? normalizedBounds(savedBounds) : defaultBounds();
     const win = new BrowserWindow({
-        width: COLLAPSED_WIDTH,
-        height: COLLAPSED_HEIGHT,
+        width: miniPref ? MINI_WIDTH : COLLAPSED_WIDTH,
+        height: miniPref ? MINI_HEIGHT : COLLAPSED_HEIGHT,
         x: bounds.x,
         y: bounds.y,
         frame: false,
@@ -126,17 +153,30 @@ function createWindow(url) {
     }
     win.on("moved", () => writeBounds(win));
     mainWindow = win;
+    const webContentsId = win.webContents.id;
     win.on("closed", () => {
-        dragState.delete(win.webContents.id);
+        dragState.delete(webContentsId);
+        stopAgentVisibilityLoop();
         if (mainWindow === win)
             mainWindow = null;
     });
     win.webContents.on("context-menu", () => {
         const menu = Menu.buildFromTemplate([
-            { label: "Hide for now", click: () => { if (!win.isDestroyed())
-                    win.hide(); } },
+            { label: "Hide for now", click: () => { hideForNow(win); } },
+            {
+                label: "Only show when Codex/Claude is open",
+                type: "checkbox",
+                checked: onlyShowWhenAgentOpen,
+                click: (item) => { setOnlyShowWhenAgentOpen(item.checked, win); },
+            },
+            {
+                label: "Show after restart",
+                type: "checkbox",
+                checked: isAutostartEnabled(),
+                click: (item) => { setAutostart(item.checked); },
+            },
             { type: "separator" },
-            { label: "Quit EchoMem HUD", click: () => app.quit() },
+            { label: "Quit EchoMem HUD", click: () => quitWithAutostartPrompt(win) },
         ]);
         menu.popup({ window: win });
     });
@@ -145,10 +185,11 @@ function createWindow(url) {
         if (shown || win.isDestroyed())
             return;
         shown = true;
-        app.focus({ steal: true });
-        win.show();
-        win.moveTop();
-        win.focus();
+        if (onlyShowWhenAgentOpen)
+            syncAgentVisibility(win);
+        else
+            showHudWindow(win, true);
+        startAgentVisibilityLoop(win);
         writeBounds(win);
     };
     win.once("ready-to-show", reveal);
@@ -158,6 +199,31 @@ function createWindow(url) {
         win.webContents.openDevTools({ mode: "detach" });
     win.loadURL(url);
 }
+// Show-after-restart registration that runs THIS electron binary on electron-main.js directly — no node
+// PATH dependency. Mirrors what `echomem-hud autostart on` writes, so CLI and menu stay in sync.
+function setAutostart(on) {
+    if (on)
+        enableAutostart([process.execPath, fileURLPath("./electron-main.js"), "--client", String(mode), "--port", String(port)]);
+    else
+        disableAutostart();
+}
+// Quitting is the moment the HUD truly disappears (unlike "Hide for now"), so if it won't come back on
+// its own, that's exactly when to offer show-after-restart — per the user's "ask me when it goes away".
+function quitWithAutostartPrompt(win) {
+    if (process.platform !== "darwin" || isAutostartEnabled())
+        return void app.quit();
+    const choice = showRecoveryPrompt({
+        buttons: ["Show after restart & quit", "Just quit", "Cancel"],
+        cancelId: 2,
+        message: "Bring EchoMem back automatically?",
+        detail: "EchoMem has no app icon to relaunch from. Turn on Show after restart and it will be waiting after your computer restarts. You can also tell your coding agent to run `echomem-hud app`.",
+    });
+    if (choice === 2)
+        return;
+    if (choice === 0)
+        setAutostart(true);
+    app.quit();
+}
 function clampExpandedHeight(value) {
     const workArea = screen.getPrimaryDisplay().workArea;
     const max = Math.max(COLLAPSED_HEIGHT, workArea.height - 48);
@@ -166,11 +232,11 @@ function clampExpandedHeight(value) {
 function showExistingWindow() {
     if (!mainWindow || mainWindow.isDestroyed())
         return;
-    if (!mainWindow.isVisible())
-        mainWindow.show();
-    mainWindow.moveTop();
-    app.focus({ steal: true });
-    mainWindow.focus();
+    manuallyHidden = false;
+    if (onlyShowWhenAgentOpen)
+        syncAgentVisibility(mainWindow);
+    else
+        showHudWindow(mainWindow, true);
 }
 async function hasCompatibleHudState(baseUrl, requestedMode) {
     const signal = AbortSignal.timeout(750);
@@ -244,7 +310,104 @@ function clamp(value, min, max) {
 function writeBounds(win) {
     const b = win.getBounds();
     fs.mkdirSync(path.dirname(boundsPath()), { recursive: true });
-    fs.writeFileSync(boundsPath(), JSON.stringify(b, null, 2));
+    fs.writeFileSync(boundsPath(), JSON.stringify({ ...b, mini: miniPref, onlyShowWhenAgentOpen }, null, 2));
+}
+function hideForNow(win) {
+    if (win.isDestroyed())
+        return;
+    if (process.platform === "darwin" && !isAutostartEnabled()) {
+        const choice = showRecoveryPrompt({
+            buttons: ["Show after restart & hide", "Hide for now", "Cancel"],
+            cancelId: 2,
+            message: "Hide EchoMem for now?",
+            detail: "It will stay hidden until you restart it. Turn on Show after restart to bring it back after your computer restarts. Before then, you can ask your coding agent to run `echomem-hud app`.",
+        });
+        if (choice === 2)
+            return;
+        if (choice === 0)
+            setAutostart(true);
+    }
+    manuallyHidden = true;
+    win.hide();
+}
+function showRecoveryPrompt(options) {
+    app.focus({ steal: true });
+    const cancelId = typeof options.cancelId === "number" ? options.cancelId : options.buttons.length - 1;
+    const { cancelId: _cancelId, ...dialogOptions } = options;
+    return dialog.showMessageBoxSync({
+        type: "question",
+        defaultId: 0,
+        cancelId,
+        icon: nativeImage.createFromPath(fileURLPath("../../assets/hud/echo-face-cutout.png")),
+        ...dialogOptions,
+    });
+}
+function setOnlyShowWhenAgentOpen(next, win) {
+    onlyShowWhenAgentOpen = next;
+    manuallyHidden = false;
+    writeBounds(win);
+    if (next)
+        syncAgentVisibility(win);
+    else
+        showHudWindow(win, true);
+}
+function startAgentVisibilityLoop(win) {
+    stopAgentVisibilityLoop();
+    visibilityTimer = setInterval(() => syncAgentVisibility(win), AGENT_VISIBILITY_POLL_MS);
+}
+function stopAgentVisibilityLoop() {
+    if (!visibilityTimer)
+        return;
+    clearInterval(visibilityTimer);
+    visibilityTimer = null;
+}
+function syncAgentVisibility(win) {
+    if (win.isDestroyed() || !onlyShowWhenAgentOpen)
+        return;
+    const frontmost = frontmostAppKind();
+    if (frontmost === "agent") {
+        if (!manuallyHidden && !win.isVisible())
+            showHudWindow(win, false);
+        else if (!manuallyHidden)
+            win.moveTop();
+        return;
+    }
+    // Leave the HUD alone while the user is interacting with the HUD/menu itself, or when macOS does
+    // not report a frontmost process. The next concrete app detection will settle visibility.
+    if (frontmost === "self" || frontmost === "unknown")
+        return;
+    if (win.isVisible())
+        win.hide();
+}
+function showHudWindow(win, focus) {
+    if (win.isDestroyed())
+        return;
+    if (focus) {
+        app.focus({ steal: true });
+        win.show();
+        win.focus();
+    }
+    else {
+        win.showInactive();
+    }
+    win.moveTop();
+}
+function frontmostAppKind() {
+    if (process.platform !== "darwin")
+        return "unknown";
+    try {
+        const name = execFileSync("osascript", ["-e", 'tell application "System Events" to get name of first application process whose frontmost is true'], { encoding: "utf8", timeout: 500, stdio: ["ignore", "pipe", "ignore"] }).trim().toLowerCase();
+        if (!name)
+            return "unknown";
+        if (name.includes("codex") || name.includes("claude"))
+            return "agent";
+        if (name.includes("echomem") || name.includes("electron") || name === app.getName().toLowerCase())
+            return "self";
+        return "other";
+    }
+    catch {
+        return "unknown";
+    }
 }
 function dragPoint(payload) {
     const startX = typeof payload.screenX === "number" && Number.isFinite(payload.screenX) ? payload.screenX : null;

package/dist/hud/metric.js

@@ -1,3 +1,4 @@
+import { calculateContextMetrics } from "../context-metrics/calculate.js";
 export const BUCKETS = {
     rangeRedundant: "range_redundant",
     staleRead: "stale_read",
@@ -72,16 +73,24 @@ export function scoreMetric(params) {
     const ct = Number(params.ctTokens) || 0;
     const modelWindow = Number(params.modelContextWindow) || 0;
     const pollutionTok = Object.values(params.state.buckets).reduce((sum, bucket) => sum + bucket.tokens, 0);
-    const pollution = ct > 0 ? Math.min(0.95, pollutionTok / ct) : 0;
+    const contextMetrics = calculateContextMetrics({
+        latestInputTokens: ct,
+        modelContextLimitTokens: modelWindow || null,
+        currentResidentWasteTokens: pollutionTok,
+    });
+    const pollution = Math.min(0.95, contextMetrics.noisePct);
     const pollutionPct = Math.round(pollution * 100);
-    const saturationPct = modelWindow > 0 ? Math.round((ct / modelWindow) * 100) : null;
+    const saturationPct = contextMetrics.contextFullnessPct !== undefined
+        ? Math.round(contextMetrics.contextFullnessPct * 100)
+        : null;
     return {
         client: params.client,
         sourcePath: params.sourcePath,
         turn: params.state.turn,
         reads: params.state.reads,
         redundantCount: params.state.redundantCount,
-        usefulPct: Math.round((1 - pollution) * 100),
+        usefulPct: Math.round(Math.max(0, Math.min(1, contextMetrics.usefulPct)) * 100),
+        healthScorePct: contextMetrics.healthScorePct,
         pollutionPct,
         pollutionTok,
         ctTokens: ct,
@@ -134,7 +143,7 @@ export function formatTokens(tokens) {
 }
 export function formatGlance(score) {
     const dot = score.color === "amber" ? "◑" : "●";
-    return `${dot} ${score.usefulPct}% clean · ${formatTokens(score.ctTokens)}`;
+    return `${dot} ${score.healthScorePct}% score · ${formatTokens(score.ctTokens)}`;
 }
 function estimateReadTokens(start, end) {
     const boundedEnd = Math.min(end, start + 4000);