@echomem/mcp 1.4.1 → 1.4.3

package/README.md

@@ -35,23 +35,57 @@ legacy EchoMem-synthesized recall answer.
 ## Quick start (recommended)
 
 ```bash
-# One command: detect your editor, write its MCP config, log in via the browser.
-npx -y @echomem/mcp setup
+# One command: install the CLI, detect your editor, write MCP config, log in via the browser.
+npm i -g @echomem/mcp@latest && echomem-mcp setup
 ```
 
-`setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP config (with **no
-secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600), then opens the
-browser to approve the device and, for encrypted accounts, unlock the vault. Reload your editor and
-you're done.
+This keeps `echomem-mcp` available for later commands like `status`, `update`, `unlock`, and
+playground setup. `setup` detects the client (Cursor / Windsurf / Claude Desktop), writes its MCP
+config (with **no secret** in it — credentials live in `~/.echomem/credentials.json`, mode 0600),
+then opens the browser to approve the device and, for encrypted accounts, unlock the vault. Reload
+your editor and you're done.
 
 | Command | What it does |
 |---|---|
+| `npm i -g @echomem/mcp@latest && echomem-mcp setup` | Install the CLI globally and run setup in one explicit step |
+| `npx -y @echomem/mcp@latest setup` | One-off setup without keeping a global CLI command |
 | `echomem-mcp setup [--client cursor\|windsurf\|claude-desktop]` | Write client config + log in |
+| `echomem-mcp setup --skip-login [--client cursor\|windsurf\|claude-desktop\|codex]` | Write client config without opening the browser or changing credentials |
+| `npx -y @echomem/mcp@latest update [--client cursor\|windsurf\|claude-desktop\|codex]` | One-shot update: repoint the client config to the latest bridge, with no browser login |
+| `echomem-mcp setup --with-hud [--client codex]` | Write client config + log in + launch the EchoMem context HUD |
 | `echomem-mcp login` | Approve device in browser (or use `--token` / `--passphrase`) |
 | `echomem-mcp unlock` | Re-derive the encryption key after its TTL (or `--passphrase`) |
 | `echomem-mcp status` | Show token / key / detected clients |
 | `echomem-mcp logout` | Remove stored credentials |
 
+The bridge reports its package version in MCP server instructions and in the `search_memories`
+tool description. Agents should use that version signal to update once when stale, not auto-update
+on every MCP startup.
+
+## EchoMem Context HUD
+
+The package also ships `echomem-hud`, a local context-health sidecar for Codex and Claude. It reads
+local agent logs, computes a tracked lower-bound "clean vs dirty" context score, and renders a small
+HUD without adding tokens to the agent conversation.
+
+```bash
+echomem-hud app                 # Electron floating HUD
+echomem-hud serve               # Browser fallback at http://127.0.0.1:17377
+echomem-hud summary --json      # Machine-readable current score
+echomem-hud status              # Show detected Codex/Claude sources
+```
+
+Supported local sources:
+- Codex: `~/.codex/sessions/**/rollout-*.jsonl`
+- Claude Code: `~/.claude/echo-ctx/*.json` first, then local transcripts when present
+- Claude desktop agent/Cowork: local agent-mode transcripts under Application Support
+
+The v1 metric counts `range_redundant` reads only and reports pollution as `tracked dead-weight ≥`
+because exact context composition and provider eviction are not observable.
+
+MCP fallback: agents can call `echo_context_health` to get the same score as markdown in-chat. This
+is on-demand; the passive HUD remains a separate local process.
+
 ### Manual / headless (SSH, containers, CI)
 
 No browser? Provide secrets directly — this is the documented headless path:
@@ -80,7 +114,7 @@ npm test   # crypto compat + encrypted-local integration tests
 
 ### Add to your IDE (Cursor or Windsurf)
 
-> Prefer `npx -y @echomem/mcp setup` above — it writes these files for you and keeps secrets out of
+> Prefer `npm i -g @echomem/mcp@latest && echomem-mcp setup` above — it writes these files for you and keeps secrets out of
 > the client config. The manual steps below are the fallback.
 
 #### For Cursor
@@ -151,6 +185,7 @@ ECHO_API_TOKEN="your_token" ECHO_API_BASE_URL="http://localhost:3000" npm run st
 * **`search_memories_by_keywords`**: Retrieve memories by matching the `keys` field.
 * **`search_others_memories`**: Search other users' public memories through MemoryFeed public search.
 * **`delete_memory`**: Delete a single personal memory through a two-step confirmation flow. First call with `memoryId` only to preview the target and receive `confirmationToken`; after the user explicitly confirms, call again with `confirmed: true` and that exact token. This deletes the memory row only and preserves raw `source_of_truth` conversation records.
+* **`echo_context_health`**: Return the local Codex/Claude context-health score as markdown. Works without login and uploads no transcript content.
 
 Legacy aliases are preserved for compatibility:
 

package/dist/hud/adapters.js

@@ -0,0 +1,288 @@
+import fs from "node:fs";
+import path from "node:path";
+import { homePath, newestFile, readJsonl, walkFiles } from "./fs.js";
+import { bumpTurn, newMetricState, recordEdit, recordRead, recordTool, scoreMetric, shellRead, } from "./metric.js";
+export const adapters = {
+    codex: {
+        client: "codex",
+        label: "Codex",
+        findActive: findActiveCodex,
+        findAll: listCodex,
+        score: scoreCodex,
+    },
+    "claude-code": {
+        client: "claude-code",
+        label: "Claude Code",
+        findActive: findActiveClaudeCode,
+        findAll: listClaudeCode,
+        score: scoreClaudeCode,
+    },
+    "claude-desktop": {
+        client: "claude-desktop",
+        label: "Claude Desktop",
+        findActive: findActiveClaudeDesktop,
+        findAll: listClaudeDesktop,
+        score: scoreClaudeDesktop,
+    },
+};
+export function adapterList(mode) {
+    if (mode === "both" || mode === "auto")
+        return Object.values(adapters);
+    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)));
+}
+function findActiveCodex() {
+    return newestFile(listCodex());
+}
+function scoreCodex(file) {
+    const state = newMetricState();
+    let ctTokens = 0;
+    let modelContextWindow = 0;
+    let compactMarkers = 0;
+    let patchEdits = 0;
+    let functionOutputs = 0;
+    let largeFunctionOutputs = 0;
+    let lastTool = "";
+    const largeByTool = {};
+    const outputTokensByTool = {};
+    const filesByTool = {};
+    let updatedAt = new Date().toISOString();
+    for (const record of readJsonl(file)) {
+        const top = isRecord(record) ? record : {};
+        const payload = isRecord(top.payload) ? top.payload : {};
+        const payloadType = typeof payload.type === "string" ? payload.type : "";
+        if (typeof top.timestamp === "string")
+            updatedAt = top.timestamp;
+        if (payloadType === "task_started")
+            bumpTurn(state);
+        else if (payloadType === "token_count") {
+            const info = isRecord(payload.info) ? payload.info : {};
+            const last = isRecord(info.last_token_usage) ? info.last_token_usage : {};
+            ctTokens = readNumber(last.input_tokens) || ctTokens;
+            modelContextWindow = readNumber(info.model_context_window) || modelContextWindow;
+        }
+        else if (payloadType === "function_call") {
+            const name = typeof payload.name === "string" ? payload.name : "";
+            recordTool(state, name);
+            if (name)
+                lastTool = name;
+            const args = parseArguments(payload.arguments);
+            const cmd = isRecord(args) && typeof args.cmd === "string" ? args.cmd : "";
+            if ((name === "exec_command" || name === "shell") && cmd) {
+                const read = shellRead(cmd);
+                if (read) {
+                    recordRead(state, read.file, read.start, read.end);
+                    addToolFile(filesByTool, name, read.file);
+                }
+            }
+        }
+        else if (payloadType === "function_call_output") {
+            functionOutputs += 1;
+            const outTool = lastTool || "output";
+            const osize = outputSize(payload.output);
+            // Image outputs (base64 PNGs) cost ~IMG_TOK, not their byte length — Kobe's calibration.
+            const outTok = /image/i.test(outTool) ? 4000 : Math.round(osize / 4);
+            outputTokensByTool[outTool] = (outputTokensByTool[outTool] || 0) + outTok;
+            if (osize > 12_000) {
+                largeFunctionOutputs += 1;
+                largeByTool[outTool] = (largeByTool[outTool] || 0) + 1;
+            }
+        }
+        else if (payloadType === "patch_apply_end") {
+            const changes = isRecord(payload.changes) ? payload.changes : {};
+            for (const changed of Object.keys(changes)) {
+                recordEdit(state, changed);
+                patchEdits += 1;
+            }
+        }
+        else if (payloadType === "context_compacted" || top.type === "compacted") {
+            compactMarkers += 1;
+        }
+    }
+    const score = scoreMetric({
+        client: "codex",
+        sourcePath: file,
+        state,
+        ctTokens,
+        ctSource: "token_count",
+        modelContextWindow,
+        updatedAt,
+        stats: { compactMarkers, patchEdits, functionOutputs, largeFunctionOutputs },
+    });
+    if (Object.keys(largeByTool).length)
+        score.largeOutputsByTool = largeByTool;
+    if (Object.keys(outputTokensByTool).length)
+        score.outputTokensByTool = outputTokensByTool;
+    if (Object.keys(filesByTool).length)
+        score.filesByTool = topFilesByTool(filesByTool);
+    return score;
+}
+function listClaudeCode() {
+    return walkFiles(homePath(".claude", "projects"), (file) => file.endsWith(".jsonl"));
+}
+function findActiveClaudeCode() {
+    const cache = newestFile(walkFiles(homePath(".claude", "echo-ctx"), (file) => file.endsWith(".json")));
+    if (cache)
+        return cache;
+    return newestFile(listClaudeCode());
+}
+function scoreClaudeCode(file) {
+    if (file.includes(`${path.sep}.claude${path.sep}echo-ctx${path.sep}`) || file.endsWith(".json")) {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        return normalizeCachedClaudeScore(raw, file, "claude-code", "statusline");
+    }
+    return scoreClaudeTranscript(file, "claude-code", "usage_estimate");
+}
+function listClaudeDesktop() {
+    const root = homePath("Library", "Application Support", "Claude", "local-agent-mode-sessions");
+    return walkFiles(root, (file) => file.endsWith(".jsonl") && file.includes(`${path.sep}.claude${path.sep}projects${path.sep}`));
+}
+function findActiveClaudeDesktop() {
+    return newestFile(listClaudeDesktop());
+}
+function scoreClaudeDesktop(file) {
+    return scoreClaudeTranscript(file, "claude-desktop", "usage_estimate");
+}
+function scoreClaudeTranscript(file, client, ctSource) {
+    const state = newMetricState();
+    let ctTokens = 0;
+    let updatedAt = new Date().toISOString();
+    const toolById = new Map();
+    const outputTokensByTool = {};
+    const filesByTool = {};
+    for (const record of readJsonl(file)) {
+        const obj = isRecord(record) ? record : {};
+        if (typeof obj.timestamp === "string")
+            updatedAt = obj.timestamp;
+        const message = isRecord(obj.message) ? obj.message : obj;
+        const role = typeof obj.type === "string" ? obj.type : typeof message.role === "string" ? message.role : "";
+        if (role === "assistant")
+            bumpTurn(state);
+        const usage = isRecord(message.usage) ? message.usage : isRecord(obj.usage) ? obj.usage : null;
+        if (usage) {
+            const input = readNumber(usage.input_tokens) || 0;
+            const cacheRead = readNumber(usage.cache_read_input_tokens) || 0;
+            const cacheCreate = readNumber(usage.cache_creation_input_tokens) || 0;
+            ctTokens = input + cacheRead + cacheCreate || ctTokens;
+        }
+        const content = Array.isArray(message.content) ? message.content : [];
+        for (const block of content) {
+            if (!isRecord(block))
+                continue;
+            if (block.type === "tool_use") {
+                const name = typeof block.name === "string" ? block.name : "";
+                if (typeof block.id === "string" && name)
+                    toolById.set(block.id, name);
+                const input = isRecord(block.input) ? block.input : {};
+                recordTool(state, name);
+                if (name === "Read" && typeof input.file_path === "string") {
+                    const start = readNumber(input.offset) || 1;
+                    const end = input.limit ? start + (readNumber(input.limit) || 1) - 1 : 1e9;
+                    recordRead(state, input.file_path, start, end);
+                    addToolFile(filesByTool, name, input.file_path);
+                }
+                else if ((name === "Edit" || name === "Write" || name === "MultiEdit") && typeof input.file_path === "string") {
+                    recordEdit(state, input.file_path);
+                    addToolFile(filesByTool, name, input.file_path);
+                }
+                else if (name === "Bash" && typeof input.command === "string") {
+                    const read = shellRead(input.command);
+                    if (read) {
+                        recordRead(state, read.file, read.start, read.end);
+                        addToolFile(filesByTool, "Bash", read.file);
+                    }
+                }
+            }
+            else if (block.type === "tool_result") {
+                const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                const tool = toolById.get(id) || "tool";
+                outputTokensByTool[tool] = (outputTokensByTool[tool] || 0) + claudeResultTokens(block.content);
+            }
+        }
+    }
+    const score = scoreMetric({ client, sourcePath: file, state, ctTokens, ctSource, updatedAt });
+    if (Object.keys(outputTokensByTool).length)
+        score.outputTokensByTool = outputTokensByTool;
+    if (Object.keys(filesByTool).length)
+        score.filesByTool = topFilesByTool(filesByTool);
+    return score;
+}
+function addToolFile(map, tool, file) {
+    if (!tool || !file)
+        return;
+    const inner = map[tool] || (map[tool] = {});
+    inner[file] = (inner[file] || 0) + 1;
+}
+function topFilesByTool(map) {
+    const out = {};
+    for (const tool of Object.keys(map)) {
+        out[tool] = Object.entries(map[tool]).sort((a, b) => b[1] - a[1]).slice(0, 12).map((entry) => entry[0]);
+    }
+    return out;
+}
+function claudeResultTokens(content) {
+    if (typeof content === "string")
+        return Math.round(outputSize(content) / 4);
+    if (Array.isArray(content)) {
+        let total = 0;
+        for (const block of content) {
+            if (!isRecord(block))
+                continue;
+            if (block.type === "image")
+                total += 4000; // IMG_TOK, not base64 byte-length
+            else if (typeof block.text === "string")
+                total += Math.round(outputSize(block.text) / 4);
+            else
+                total += Math.round(outputSize(block) / 4);
+        }
+        return total;
+    }
+    return Math.round(outputSize(content) / 4);
+}
+function normalizeCachedClaudeScore(raw, file, client, ctSource) {
+    const ctTokens = readNumber(raw.ctTokens) || readNumber(raw.size) || readNumber(raw.contextTokens) || 0;
+    const pollutionTok = readNumber(raw.pollutionTok) || readNumber(raw.redundantTok) || readNumber(raw.pollution_tokens) || 0;
+    const state = newMetricState();
+    state.turn = readNumber(raw.turn) || 0;
+    state.reads = readNumber(raw.reads) || 0;
+    state.redundantCount = readNumber(raw.redundantCount) || 0;
+    state.buckets.range_redundant.tokens = pollutionTok;
+    state.buckets.range_redundant.count = state.redundantCount;
+    return scoreMetric({
+        client,
+        sourcePath: file,
+        state,
+        ctTokens,
+        ctSource,
+        modelContextWindow: readNumber(raw.modelContextWindow) || null,
+        updatedAt: new Date().toISOString(),
+    });
+}
+function parseArguments(value) {
+    if (!value)
+        return {};
+    if (isRecord(value))
+        return value;
+    if (typeof value !== "string")
+        return {};
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return {};
+    }
+}
+function outputSize(value) {
+    if (typeof value === "string")
+        return Buffer.byteLength(value);
+    return Buffer.byteLength(JSON.stringify(value || ""));
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/hud/api.js

@@ -0,0 +1,29 @@
+import { HudMonitor } from "./monitor.js";
+import { renderStateText } from "./render.js";
+import { buildCapsuleText } from "./capsule.js";
+export async function contextHealthMarkdown(mode = "auto") {
+    const state = await snapshot(mode);
+    const base = renderStateText(state);
+    const active = state.active;
+    // When the window is amber/red, point the agent at the action half of the loop.
+    if (active && active.color !== "green") {
+        const sat = active.saturationPct !== null ? `${active.saturationPct}% full · ` : "";
+        return `${base}\n\n→ Context is heavy (${sat}${active.pollutionPct}% tracked pollution). Call echo_recompose to capture a clean-start capsule and begin a fresh session before the window auto-compacts.`;
+    }
+    return base;
+}
+export async function recomposeCapsuleMarkdown(mode = "auto") {
+    const state = await snapshot(mode);
+    if (!state.active) {
+        return "EchoMem: no active local Codex/Claude session found to recompose. Open a coding session and try again.";
+    }
+    return buildCapsuleText(state.active);
+}
+async function snapshot(mode) {
+    const monitor = new HudMonitor(mode, 250);
+    monitor.start();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    const state = monitor.snapshot();
+    monitor.stop();
+    return state;
+}

package/dist/hud/capsule.js

@@ -0,0 +1,125 @@
+// Builds an inspectable "clean-start capsule" from the active local session: the goal, the files in
+// play, the most recent instruction, and where things stand. Reuses the scorer's Score for the
+// working set + health numbers, and does one tolerant pass over the raw log for user turns + edits.
+// Pull model only — returns text the user pastes into a fresh session; it never mutates the live
+// window (no provider API for that). Tracked-lower-bound honesty matches the rest of the HUD.
+import { readJsonl } from "./fs.js";
+import { clientLabel } from "./render.js";
+import { formatTokens } from "./metric.js";
+const MAX_TURN_CHARS = 280;
+const MAX_FILES = 10;
+export function buildCapsuleText(score) {
+    const { turns, edited } = scanSession(score.sourcePath);
+    const goal = turns[0];
+    const lastAsk = turns.length > 1 ? turns[turns.length - 1] : undefined;
+    const reads = readFiles(score, edited);
+    const sat = score.saturationPct !== null
+        ? ` · ${score.saturationPct}% of ${formatTokens(score.modelContextWindow || 0)} window`
+        : "";
+    const lines = [
+        `# EchoMem clean-start capsule — ${clientLabel(score.client)}`,
+        `Captured ${score.updatedAt} · ${score.usefulPct}% clean${sat}`,
+        "",
+        "## Goal",
+        goal || "(state the goal of this session)",
+    ];
+    if (lastAsk)
+        lines.push("", "## Most recent instruction", lastAsk);
+    if (edited.length)
+        lines.push("", "## Files being edited", ...edited.slice(0, MAX_FILES).map((f) => `- ${f}`));
+    if (reads.length)
+        lines.push("", "## Other files read", ...reads.slice(0, MAX_FILES).map((f) => `- ${f}`));
+    lines.push("", "## Where things stand", `- Turns ${score.turn} · reads ${score.reads} · edits ${score.stats?.patchEdits ?? 0} · compactions ${score.stats?.compactMarkers ?? 0}`, `- Tracked dead-weight ≥ ${formatTokens(score.pollutionTok)} (${score.pollutionPct}% pollution, lower bound)`, "", "---", "Start a fresh session and paste this capsule (or call search_memories) so the new window begins clean — you keep the goal, the working set, and your last instruction without re-reading everything. This is a clean recompose, not a provider compaction.");
+    return lines.join("\n");
+}
+// Read files the scorer already tracked, minus anything we know was edited (shown separately).
+function readFiles(score, edited) {
+    const editedSet = new Set(edited);
+    const seen = new Set();
+    for (const files of Object.values(score.filesByTool || {})) {
+        for (const file of files) {
+            if (file && !editedSet.has(file))
+                seen.add(file);
+        }
+    }
+    return [...seen];
+}
+function scanSession(file) {
+    const turns = [];
+    const edited = new Set();
+    let records = [];
+    try {
+        records = readJsonl(file);
+    }
+    catch {
+        return { turns, edited: [] };
+    }
+    for (const record of records) {
+        if (!isRecord(record))
+            continue;
+        const text = userTextFromRecord(record);
+        if (text)
+            turns.push(text);
+        collectEdited(record, edited);
+    }
+    return { turns, edited: [...edited] };
+}
+// Tolerant across Codex (payload.role/payload.content) and Claude (message.role/message.content)
+// shapes. Skips tool results, assistant turns, and injected <context> wrappers; degrades to nothing
+// rather than throwing, so the capsule still renders from the working set + health.
+function userTextFromRecord(record) {
+    const payload = isRecord(record.payload) ? record.payload : record;
+    const message = isRecord(payload.message) ? payload.message : isRecord(record.message) ? record.message : null;
+    let role = "";
+    if (typeof payload.role === "string")
+        role = payload.role;
+    else if (message && typeof message.role === "string")
+        role = message.role;
+    else if (typeof record.type === "string")
+        role = record.type;
+    const ptype = typeof payload.type === "string" ? payload.type : "";
+    if (role !== "user" && ptype !== "user_message")
+        return null;
+    const raw = (message ? message.content : undefined) ?? payload.content ?? payload.text;
+    const text = clean(flatten(raw));
+    if (!text || text.startsWith("<") || text.length < 3)
+        return null;
+    return text.length > MAX_TURN_CHARS ? `${text.slice(0, MAX_TURN_CHARS)}…` : text;
+}
+function collectEdited(record, set) {
+    const payload = isRecord(record.payload) ? record.payload : record;
+    if (payload.type === "patch_apply_end" && isRecord(payload.changes)) {
+        for (const file of Object.keys(payload.changes))
+            if (file)
+                set.add(file);
+    }
+    const message = isRecord(record.message) ? record.message : payload;
+    const content = Array.isArray(message.content) ? message.content : [];
+    for (const block of content) {
+        if (!isRecord(block) || block.type !== "tool_use")
+            continue;
+        const name = typeof block.name === "string" ? block.name : "";
+        const input = isRecord(block.input) ? block.input : {};
+        if ((name === "Edit" || name === "Write" || name === "MultiEdit") && typeof input.file_path === "string") {
+            set.add(input.file_path);
+        }
+    }
+}
+function flatten(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((block) => (typeof block === "string" ? block : isRecord(block) && typeof block.text === "string" ? block.text : ""))
+            .join(" ");
+    }
+    if (isRecord(content) && typeof content.text === "string")
+        return content.text;
+    return "";
+}
+function clean(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/hud/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { adapterList } from "./adapters.js";
+import { statSignature } from "./fs.js";
+import { installHooks } from "./hooks.js";
+import { HudMonitor } from "./monitor.js";
+import { renderStateText } from "./render.js";
+import { renderReportText, runReport } from "./report.js";
+import { createHudServer } from "./server.js";
+const argv = process.argv.slice(2);
+const command = argv[0] || "summary";
+const flags = parseFlags(argv.slice(1));
+try {
+    if (command === "summary")
+        await cmdSummary(flags);
+    else if (command === "watch")
+        await cmdWatch(flags);
+    else if (command === "serve")
+        await cmdServe(flags);
+    else if (command === "app")
+        await cmdApp(flags);
+    else if (command === "install-hooks")
+        await cmdInstallHooks(flags);
+    else if (command === "status")
+        await cmdStatus(flags);
+    else if (command === "report")
+        await cmdReport(flags);
+    else if (command === "help" || command === "--help" || command === "-h")
+        printHelp();
+    else {
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exitCode = 1;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+async function cmdSummary(flags) {
+    const mode = parseMode(flags.client);
+    const monitor = new HudMonitor(mode, 250);
+    monitor.start();
+    await sleep(300);
+    const state = monitor.snapshot();
+    monitor.stop();
+    if (flags.json)
+        console.log(JSON.stringify(state.active || state, null, 2));
+    else
+        console.log(renderStateText(state));
+}
+async function cmdWatch(flags) {
+    const mode = parseMode(flags.client);
+    const monitor = new HudMonitor(mode, readNumber(flags["poll-ms"], 750));
+    monitor.on("state", (state) => {
+        if (flags.json)
+            console.log(JSON.stringify(state.active || state));
+        else
+            console.log(`${new Date().toLocaleTimeString()}  ${state.active ? renderStateText(state).split("\n")[0] : "no source"}`);
+    });
+    monitor.start();
+}
+async function cmdServe(flags) {
+    const server = await createHudServer({
+        mode: parseMode(flags.client),
+        port: readNumber(flags.port, 17377),
+        pollMs: readNumber(flags["poll-ms"], 750),
+    });
+    console.log(`EchoMem HUD listening at ${server.url}`);
+}
+async function cmdApp(flags) {
+    const require = createRequire(import.meta.url);
+    const electronPath = require("electron");
+    const mainPath = fileURLToPath(new URL("./electron-main.js", import.meta.url));
+    const args = [mainPath, "--client", String(flags.client || "auto"), "--port", String(flags.port || 17377)];
+    const child = spawn(electronPath, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    console.log("EchoMem HUD app launched.");
+}
+async function cmdInstallHooks(flags) {
+    const paths = installHooks(parseMode(flags.client));
+    console.log(`Installed EchoMem HUD hook support:\n${paths.map((p) => `- ${p}`).join("\n")}`);
+    console.log("Codex users: run /hooks in a new Codex session to review and trust changed hooks.");
+}
+async function cmdReport(flags) {
+    const result = runReport(parseMode(flags.client), { limit: readNumber(flags.limit, 40) });
+    if (flags.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(renderReportText(result));
+}
+async function cmdStatus(flags) {
+    const mode = parseMode(flags.client);
+    for (const adapter of adapterList(mode)) {
+        const file = adapter.findActive();
+        console.log(`${adapter.label}: ${file ? `found (${statSignature(file).split(":").slice(1).join(":")}) ${file}` : "missing"}`);
+    }
+}
+function parseFlags(args) {
+    const parsed = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg.startsWith("--"))
+            continue;
+        const key = arg.slice(2);
+        const next = args[i + 1];
+        if (next && !next.startsWith("--")) {
+            parsed[key] = next;
+            i += 1;
+        }
+        else {
+            parsed[key] = true;
+        }
+    }
+    return parsed;
+}
+function parseMode(value) {
+    return value === "codex" || value === "claude-code" || value === "claude-desktop" || value === "both" || value === "auto"
+        ? value
+        : "auto";
+}
+function readNumber(value, fallback) {
+    return typeof value === "string" ? Number(value) || fallback : fallback;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function printHelp() {
+    console.log(`EchoMem HUD
+
+Usage:
+  echomem-hud summary [--client codex|claude-code|claude-desktop|auto] [--json]
+  echomem-hud watch [--client codex|claude-code|claude-desktop|auto] [--json]
+  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 status
+  echomem-hud report [--client codex|claude-code|claude-desktop|auto] [--limit 40] [--json]
+`);
+}