feat: engram hud-label command for Claude HUD integration

New CLI command `engram hud-label` outputs JSON for Claude HUD's
--extra-cmd protocol. Shows ⚡engram with token savings + visual
hit rate bar (▰/▱). Runs in <20ms via hook-log parsing.

Users can add to their Claude HUD:
  --extra-cmd="engram hud-label"

States: ready → listening → savings + bar + percentage.
Bar fills as hit rate climbs. Savings number grows over session.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NickCirv

package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "The structural code graph your AI agent can't forget to use. A Claude Code hook layer that intercepts Read/Edit/Write/Bash and replaces file contents with ~300-token structural graph summaries. 82% measured token reduction. Context rot is empirically solved — cite Chroma. Local SQLite, zero LLM cost, zero cloud, zero native deps.",
   "type": "module",
   "bin": {

src/cli.ts

@@ -192,6 +192,60 @@ program
     await new Promise(() => {});
   });
 
+program
+  .command("hud-label")
+  .description("Output JSON label for Claude HUD --extra-cmd (fast, <20ms)")
+  .argument("[path]", "Project directory", ".")
+  .action(async (projectPath: string) => {
+    const resolvedPath = pathResolve(projectPath);
+    const logPath = join(resolvedPath, ".engram", "hook-log.jsonl");
+
+    if (!existsSync(join(resolvedPath, ".engram", "graph.db"))) {
+      console.log('{"label":""}');
+      return;
+    }
+
+    if (!existsSync(logPath)) {
+      console.log('{"label":"⚡engram ░░░░░░░░░░ ready"}');
+      return;
+    }
+
+    try {
+      const entries = readHookLog(resolvedPath);
+      const summary = summarizeHookLog(entries);
+
+      if (summary.totalInvocations === 0) {
+        console.log('{"label":"⚡engram ░░░░░░░░░░ listening..."}');
+        return;
+      }
+
+      const totalPreTool =
+        (summary.byDecision["deny"] ?? 0) +
+        (summary.byDecision["allow"] ?? 0) +
+        (summary.byDecision["passthrough"] ?? 0);
+      const denied = summary.readDenyCount;
+      const hitRate = totalPreTool > 0 ? Math.round((denied / totalPreTool) * 100) : 0;
+      const tokens = summary.estimatedTokensSaved;
+
+      // Format tokens
+      let formatted: string;
+      if (tokens >= 1_000_000) formatted = (tokens / 1_000_000).toFixed(1) + "M";
+      else if (tokens >= 1_000) formatted = (tokens / 1_000).toFixed(1) + "K";
+      else formatted = String(tokens);
+
+      // Build bar (10 chars)
+      const barWidth = 10;
+      let filled = Math.round((hitRate / 100) * barWidth);
+      if (filled > barWidth) filled = barWidth;
+      if (denied > 0 && filled === 0) filled = 1;
+      const bar = "▰".repeat(filled) + "▱".repeat(barWidth - filled);
+
+      console.log(JSON.stringify({ label: `⚡engram ${formatted} saved ${bar} ${hitRate}%` }));
+    } catch {
+      console.log('{"label":"⚡engram"}');
+    }
+  });
+
 program
   .command("query")
   .description("Query the knowledge graph")