claude-code-memory-explorer 0.17.0 → 1.0.0

package/hub-app.json

@@ -0,0 +1,25 @@
+{
+  "manifest": 1,
+  "id": "memory",
+  "name": "Memory Diagnoser",
+  "icon": "database",
+  "run": { "entry": "server.js", "defaultPort": 3544 },
+  "loading": {
+    "verbs": [
+      "Recalling memories…",
+      "Walking the tree…",
+      "Dusting off notes…",
+      "Reading CLAUDE.md…",
+      "Following imports…",
+      "Tracing the context…",
+      "Flipping through pages…",
+      "Connecting the dots…",
+      "Checking what sticks…"
+    ]
+  },
+  "actions": {
+    "handles": {
+      "project.memory": { "params": { "project": "string?" }, "url": "?project={project}", "mode": "message" }
+    }
+  }
+}

package/lib/net-guard.js

@@ -36,6 +36,7 @@ const PORT_RE = /^[0-9]{1,5}$/;
 // The port is validated but not compared — the listen(0) fallbacks make the real
 // port dynamic, so only the host is allowlisted.
 const validPort = (p) => PORT_RE.test(p) && Number(p) >= 1 && Number(p) <= 65535;
+const KEEP_ALIVE_MS = 65000;
 
 function isLoopbackAddress(host) {
   if (!host) return false;
@@ -249,6 +250,10 @@ function createNetGuard(config = {}) {
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
     const makeServer = (handler) => {
       const s = http.createServer(serverOpts, handler);
+      // Node's 5 s default closes idle sockets that the hub proxy and the browser would reuse, and a
+      // fresh loopback connect is the one that some Windows network filters drop. The hub's agent
+      // drops its idle sockets before this, so it never reuses one the server is closing.
+      s.keepAliveTimeout = KEEP_ALIVE_MS;
       if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
       return s;
     };
@@ -281,4 +286,4 @@ function createNetGuard(config = {}) {
   return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
-module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };
+module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress, KEEP_ALIVE_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-memory-explorer",
-  "version": "0.17.0",
+  "version": "1.0.0",
   "description": "Memory explorer dashboard for Claude Code",
   "main": "server.js",
   "type": "commonjs",
@@ -46,6 +46,7 @@
   "license": "MIT",
   "files": [
     "server.js",
+    "hub-app.json",
     "lib/",
     "public/",
     "README.md",

package/public/app.js

@@ -145,15 +145,17 @@ function setColorTheme(id) {
   syncColorThemeMenu(id);
 }
 
-function buildThemeMenu() {
+function buildThemeMenu(themes = COLOR_THEMES) {
   const menu = document.getElementById('themeMenu');
-  menu.innerHTML = COLOR_THEMES.map(
-    ([id, label]) =>
-      `<button type="button" class="theme-menu-item theme-swatch-${id}" data-theme-id="${id}"
+  menu.innerHTML = themes
+    .map(
+      ([id, label]) =>
+        `<button type="button" class="theme-menu-item theme-swatch-${id}" data-theme-id="${id}"
          onclick="event.stopPropagation(); setColorTheme('${id}'); toggleThemeMenu()">
-         <span class="theme-swatch theme-swatch-${id}"><i class="sw-bg"></i><i class="sw-accent"></i><i class="sw-ink"></i></span>${label}
+         <span class="theme-swatch theme-swatch-${id}"><i class="sw-bg"></i><i class="sw-accent"></i><i class="sw-ink"></i></span>${esc(label)}
        </button>`,
-  ).join('');
+    )
+    .join('');
 }
 
 // biome-ignore lint/correctness/noUnusedVariables: called from topbar markup
@@ -453,6 +455,8 @@ const SHORTCUT_PAIRS = [
         { keys: ['Ctrl', 'Alt', '←/→'], combo: true, label: 'Previous / next hub app' },
         { keys: ['Alt', '1…9'], combo: true, label: 'Jump to hub app by number' },
         { keys: ['Ctrl', 'Alt', 'P'], combo: true, label: 'Project picker' },
+        { keys: ['Ctrl', 'Alt', 'W'], combo: true, label: 'Config dir picker' },
+        { keys: ['Ctrl', 'Alt', 'A'], combo: true, label: 'App launcher' },
       ],
     },
   ],
@@ -490,7 +494,7 @@ function buildHelpShortcuts() {
 function toggleHelpModal() {
   const list = document.getElementById('helpShortcuts');
   if (!list.childElementCount) list.innerHTML = buildHelpShortcuts();
-  list.classList.toggle('sc-standalone', !window.__HUB__?.enabled);
+  list.classList.toggle('sc-standalone', hub.status === 'standalone');
   document.getElementById('helpModal').classList.toggle('open');
 }
 
@@ -2137,117 +2141,47 @@ document.addEventListener('keydown', (e) => {
 
 // #region HUB_INTEGRATION
 
-(async function initHub() {
-  const cfg = await fetch('/hub-config')
-    .then((r) => r.json())
-    .catch(() => ({}));
-  if (!cfg.enabled) return;
-  window.__HUB__ = cfg;
-  // e.code travels with e.key because macOS composes Option+<key> into a character (Option+P is
-  // 'π'), so the key alone cannot identify the binding. The hub owns the keymap and normalizes;
-  // these tests only decide whether a press is the hub's to handle.
-  document.addEventListener('keydown', (e) => {
-    if (!isHubKey(e)) return;
-    e.preventDefault();
-    hubPost({ type: 'hub:keydown', key: e.key, code: e.code, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey });
-  });
-})();
-
-// The combos the hub binds, from its hub:keys message. Null until one arrives: a hub from before
-// hub:keys sends none, and the fallback filter below is what such a hub expects.
-let hubKeys = null;
-
-// A copy of the hub's comboOf(): its names must match the hub:keys list.
-function hubCombo(e) {
-  const lower = (e.key || '').toLowerCase();
-  const m = /^(?:Key|Digit)([A-Z1-9])$/.exec(e.code || '');
-  const key = /^[a-z1-9]$/.test(lower) ? lower : m ? m[1].toLowerCase() : e.key;
-  const mods = [e.ctrlKey && 'ctrl', e.altKey && 'alt', e.shiftKey && 'shift', e.metaKey && 'meta'];
-  return [...mods, key].filter(Boolean).join('+');
-}
-
-function isHubKey(e) {
-  if (hubKeys) return hubKeys.has(hubCombo(e));
-  if (e.ctrlKey && e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) return true;
-  // Own branch: the Alt+digit case below requires !ctrlKey. The hub owns the Ctrl+Alt+letter
-  // keymap and ignores unbound letters.
-  if (e.ctrlKey && e.altKey && !e.shiftKey && !e.metaKey && (/^[a-z]$/i.test(e.key) || /^Key[A-Z]$/.test(e.code))) {
-    return true;
-  }
-  return e.altKey && !e.ctrlKey && !e.shiftKey && !e.metaKey && (/^[1-9]$/.test(e.key) || /^Digit[1-9]$/.test(e.code));
-}
-
-function _hubNavigate(app, url) {
-  if (!window.__HUB__?.enabled) return;
-  hubPost({ type: 'hub:navigate', app, url });
-}
-
-// Hoisted out of initHubTheme so initHubProject can share it.
-const hubOrigin = () => (window.__HUB__?.url ? new URL(window.__HUB__.url).origin : null);
+const hub = ClaudeHub.connect();
 
-// Every send is addressed to the hub explicitly. With targetOrigin '*' any page that
-// framed this app also received the forwarded keystrokes and navigation intents.
-function hubPost(message) {
-  const origin = hubOrigin();
-  if (origin) window.parent?.postMessage(message, origin);
-}
+document.getElementById('helpDocs')?.addEventListener('click', (e) => {
+  e.preventDefault();
+  hub.openExternal(e.currentTarget.href);
+});
 
 (function initHubTheme() {
   const getTheme = () => (document.body.classList.contains('light') ? 'light' : 'dark');
   const getColorTheme = () => document.body.dataset.colorTheme || 'ember';
-  // lastTheme/lastColorTheme are updated synchronously when applying a hub
-  // message, so the (async) observer sees no diff and doesn't echo it back.
-  let lastTheme = getTheme();
-  let lastColorTheme = getColorTheme();
-  window.addEventListener('message', (e) => {
-    if (e.source !== window.parent || e.origin !== hubOrigin()) return;
-    if (e.data?.type !== 'hub:theme') return;
-    if (typeof e.data.colorTheme === 'string' && e.data.colorTheme !== getColorTheme()) {
-      setColorTheme(e.data.colorTheme);
-      lastColorTheme = getColorTheme();
-    }
-    if (getTheme() !== e.data.theme) {
-      window.toggleTheme();
-      lastTheme = getTheme();
-    }
+  const report = hub.bindTheme({
+    get: () => ({ theme: getTheme(), colorTheme: getColorTheme() }),
+    set: ({ theme, colorTheme }) => {
+      if (colorTheme !== getColorTheme()) setColorTheme(colorTheme);
+      if (theme !== getTheme()) window.toggleTheme();
+    },
   });
-  new MutationObserver(() => {
-    const t = getTheme();
-    const ct = getColorTheme();
-    if (t === lastTheme && ct === lastColorTheme) return;
-    lastTheme = t;
-    lastColorTheme = ct;
-    hubPost({ type: 'hub:theme', theme: t, colorTheme: ct });
-  }).observe(document.body, {
+  new MutationObserver(report).observe(document.body, {
     attributes: true,
     attributeFilter: ['class', 'data-color-theme'],
   });
 })();
 
-(function initHubKeys() {
-  window.addEventListener('message', (e) => {
-    if (e.source !== window.parent || e.origin !== hubOrigin()) return;
-    if (e.data?.type !== 'hub:keys' || !Array.isArray(e.data.keys)) return;
-    hubKeys = new Set(e.data.keys.filter((k) => typeof k === 'string'));
-  });
-})();
+// Under the hub the picker lists the hub's themes, which include the user's own (protocol section 6, rule 5).
+hub.onThemes((themes) => {
+  buildThemeMenu(themes.map((t) => [t.id, t.label]));
+  syncColorThemeMenu(document.body.dataset.colorTheme);
+});
 
 // Set synchronously when the hub pushes a project, so the DOMContentLoaded restore below can't
 // let a stale localStorage recent win the race against the hub's choice.
 let hubProjectPath = null;
+// Shared with the DOMContentLoaded restore so a boot restore and a hub push never apply the same project twice.
+let lastAppliedProject = null;
 
 (function initHubProject() {
-  let lastApplied = null;
-  window.addEventListener('message', async (e) => {
-    if (e.source !== window.parent || e.origin !== hubOrigin()) return;
-    if (e.data?.type !== 'hub:project') return;
-    const dirPath = e.data.project;
-    if (typeof dirPath !== 'string' || !dirPath) return;
-    hubProjectPath = dirPath;
+  async function applyProject(dirPath) {
     // Dedupes against the last applied value, not just an in-flight one: the hub re-posts on
     // every iframe load, so without this each load would PUT and reload twice.
-    if (lastApplied === dirPath) return;
-    lastApplied = dirPath;
+    if (lastAppliedProject === dirPath) return;
+    lastAppliedProject = dirPath;
     try {
       await putProject(dirPath);
       // The hub does not persist its own scope, so a hub-pushed project must become the recent
@@ -2256,9 +2190,22 @@ let hubProjectPath = null;
       addRecentProject(dirPath);
       await Promise.all([loadProject(), loadData()]);
     } catch (err) {
-      lastApplied = null;
-      console.warn('hub:project failed:', err.message);
+      lastAppliedProject = null;
+      throw err;
     }
+  }
+
+  hub.subscribe('project.changed', (p) => {
+    const dirPath = typeof p?.project === 'string' && p.project ? p.project : null;
+    if (!dirPath) return;
+    hubProjectPath = dirPath;
+    applyProject(dirPath).catch((err) => console.warn('project.changed failed:', err.message));
+  });
+
+  // A link moves this app off the hub's project, and applyProject records that, so the next
+  // project.changed still applies.
+  hub.handle('project.memory', (p) => {
+    if (p.project) applyProject(p.project).catch(() => showToast('Failed to switch project', 'error'));
   });
 })();
 
@@ -2320,11 +2267,13 @@ document.addEventListener('DOMContentLoaded', async () => {
   // Handle ?project= query param, else restore last-used project from localStorage
   const params = new URLSearchParams(location.search);
   let desiredProject = params.get('project');
-  // A hub-pushed project outranks the localStorage recent: initHub() is fire-and-forget at script
-  // eval, so hub:project can land before or during this block.
+  // A hub-pushed project outranks the localStorage recent: ClaudeHub.connect() is fire-and-forget at script
+  // eval, so project.changed can land before or during this block.
   await projectInfoPromise;
   if (!desiredProject) desiredProject = hubProjectPath || getRecentProjects()[0] || null;
   if (desiredProject) {
+    // Set before the PUT: the hub's push can land while it is in flight.
+    lastAppliedProject = desiredProject;
     try {
       await putProject(desiredProject);
     } catch {

package/public/index.html

@@ -27,6 +27,7 @@
 <script defer src="/app.js"></script>
 </head>
 <body>
+<script src="/vendor/claude-hub-sdk.js"></script>
   <div class="topbar">
     <div class="topbar-logo">
       <div class="logo-mark"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5v4c0 1.66 4.03 3 9 3s9-1.34 9-3V5"/><path d="M3 9v4c0 1.66 4.03 3 9 3s9-1.34 9-3V9"/><path d="M3 13v4c0 1.66 4.03 3 9 3s9-1.34 9-3v-4"/></svg></div>
@@ -166,6 +167,7 @@
     <div class="modal modal-help">
       <div class="modal-header">
         <h3>Memory Diagnoser</h3>
+        <a class="help-docs" id="helpDocs" href="https://nikiforovall.blog/claude-code-memory/" target="_blank" rel="noopener">Docs ↗</a>
         <button class="modal-close" onclick="toggleHelpModal()">&#10005;</button>
       </div>
       <div class="modal-body">

package/public/style.css

@@ -964,6 +964,23 @@ body.light .tree-conditional .file-name {
   margin-bottom: 6px;
   text-transform: uppercase;
 }
+.help-docs {
+  margin: 0 12px 0 auto;
+  padding: 4px 10px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--text-secondary);
+  font-size: 12px;
+  text-decoration: none;
+  white-space: nowrap;
+  transition:
+    color 0.15s ease,
+    border-color 0.15s ease;
+}
+.help-docs:hover {
+  color: var(--accent);
+  border-color: var(--accent);
+}
 /* One shared grid for both halves (key | label | spacer | key | label): each key
    gutter is sized by its column's widest combo, and left/right rows share row
    tracks, so paired groups line up — a shorter group just leaves empty rows.

package/public/vendor/claude-hub-sdk.js

@@ -0,0 +1,50 @@
+// claude-hub-sdk 1.1.0 (sha256 0fed14faa670). Copied by npm run sdk:sync in claude-code-hub. Do not edit.
+// Claude Code Hub SDK stub: what an app serves when no hub runs it. Under a hub, the hub hands the
+// app its real SDK (client.js) in place of this file. The API must match client.js; a test checks it.
+((root) => {
+  'use strict';
+
+  function createClaudeHub(win) {
+    let hub = null;
+    const off = () => {};
+
+    function connect({ standalone = {} } = {}) {
+      if (hub) return hub;
+      const standaloneFn = (action) => {
+        const fn = (typeof standalone === 'function' ? standalone() : standalone)[action];
+        return typeof fn === 'function' ? fn : null;
+      };
+      hub = {
+        status: 'standalone',
+        themes: [],
+        inHub: false,
+        onStatus: () => off,
+        onActive: () => off,
+        onThemes: () => off,
+        subscribe: () => off,
+        bindTheme: () => off,
+        handle() {},
+        publish() {},
+        invoke(action, params = {}) {
+          const target = standaloneFn(action)?.(params);
+          if (!target) return Promise.resolve({ ok: false, reason: 'unhandled' });
+          win.open(target, '_blank', 'noopener');
+          return Promise.resolve({ ok: true, handledBy: 'standalone' });
+        },
+        can: (action) => !!standaloneFn(action),
+        forwards: () => false,
+        closeGuard() {},
+        openExternal(url) {
+          win.open(url, '_blank', 'noopener');
+        },
+        terminalToken: () => Promise.resolve(null),
+      };
+      return hub;
+    }
+
+    return { connect };
+  }
+
+  if (typeof module === 'object' && module.exports) module.exports = { createClaudeHub };
+  else root.ClaudeHub = createClaudeHub(root);
+})(typeof window !== 'undefined' ? window : globalThis);

package/server.js

@@ -608,18 +608,10 @@ app.use(net.frameGuard);
 app.use(net.originGuard);
 
 app.use(express.json());
+// Under a hub, the hub hands over its SDK. Alone, public/vendor/claude-hub-sdk.js is a stub.
+if (process.env.HUB_SDK_SERVER) require(process.env.HUB_SDK_SERVER).mount(app);
 app.use(express.static(path.join(__dirname, 'public')));
 
-app.get('/hub-config', (_req, res) => {
-  res.json({
-    name: 'Memory Diagnoser',
-    icon: 'brain',
-    description: 'Explore Claude Code memory sources',
-    enabled: !!process.env.CLAUDE_HUB,
-    url: process.env.HUB_URL || null,
-  });
-});
-
 app.get('/api/project', (_req, res) => {
   res.json({ path: currentProjectPath, name: path.basename(currentProjectPath), configDir: CLAUDE_DIR });
 });