claude-code-memory-explorer 0.6.0 → 0.9.0

package/README.md

@@ -4,7 +4,11 @@
 [![license](https://img.shields.io/npm/l/claude-code-memory-explorer)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/claude-code-memory-explorer)](https://www.npmjs.com/package/claude-code-memory-explorer)
 
-> See everything Claude Code knows about your project — CLAUDE.md files, rules, auto memory, and imports.
+**[Live Demo & Docs](https://nikiforovall.blog/claude-code-memory/)**
+
+> See everything Claude Code knows about your project — CLAUDE.md files, rules, auto memory, agent memory, and imports.
+
+![Memory explorer overview](assets/shot-overview.png)
 
 ## Getting Started
 
@@ -12,81 +16,35 @@
 npx claude-code-memory-explorer --open
 ```
 
-Open http://localhost:3544 (or use `--open` to auto-launch the browser).
-
-That's it. No config — the dashboard reads your existing Claude Code memory files.
-
-![Dark theme](assets/main-dark.png)
-![Light theme](assets/main-light.png)
+That's it — no config. The dashboard scans the Claude Code memory locations for the current project and renders the full stack. Completely read-only; nothing leaves your machine.
 
 ## Features
 
-- **Full memory stack** — User CLAUDE.md, project CLAUDE.md, CLAUDE.local.md, rules, auto memory, and managed policies
-- **Import resolution** — Follows `@path/to/file.md` references and `[text](file.md)` markdown links up to 5 levels deep
-- **Rules inspection** — Shows path-scoped frontmatter (`paths`, `type`, `name`) with conditional load indicators
-- **Auto memory** — Visualizes MEMORY.md with startup cutoff line, on-demand topic files, and frontmatter badges
-- **Tree + preview** — Left panel grouped by scope (user/project/rules/memory), right panel with syntax-highlighted preview
-- **Keyboard-driven** — j/k navigation, h/l group jump, e to open in editor, t for theme, ? for help
-- **Resizable sidebar** — Drag handle between tree and preview, width persisted
-- **Browser history** — Back/forward navigates file selection, bookmarkable URLs
-- **Dark & light theme** — Dark default, light toggle with `t` key
-- **Hub integration** — Works as a tab in Claude Code Hub alongside Cost and Marketplace
+- **Full memory stack** — user CLAUDE.md, project CLAUDE.md, CLAUDE.local.md, rules, auto memory, agent memory, and managed policies in one view
+- **Import resolution** — follows `@path/to/file.md` references and `[text](file.md)` markdown links up to 5 levels deep, clickable in the preview
+- **Rules inspection** — path-scoped frontmatter (`paths`, `type`, `name`) with conditional load indicators
+- **Auto memory** — MEMORY.md with startup badge, on-demand topic files, and frontmatter badges
+- **Agent memory** — subagent persistent memory at user, project, and local scope, grouped per agent
+- **Keyboard-driven** — j/k navigation, h/l group jump, e to open in editor, Shift+P project picker, ? for help
+- **17 color themes** — Ember, Gruvbox, Catppuccin, Tokyo Night, Dracula, Nord, and more — each in light and dark, PWA installable
+- **Hub integration** — runs standalone or as a tab in [Claude Code Hub](https://github.com/NikiforovAll/claude-code-hub) alongside Kanban, Cost, and Marketplace
 
-## Configuration
+![Path-scoped rule with frontmatter badges](assets/shot-rules.png)
 
-```bash
-PORT=8080 npx claude-code-memory-explorer              # Custom port
-npx claude-code-memory-explorer --open                 # Auto-open browser
-npx claude-code-memory-explorer --dir=~/.claude-work   # Custom Claude config dir
-npx claude-code-memory-explorer --project=/path/to/project  # Specify project path
-```
+![Auto memory index with topic files](assets/shot-auto-memory.png)
 
-If port 3544 is in use, the server falls back to a random available port.
+![Dark theme — Tokyo Night](assets/shot-dark-theme.png)
 
-### Global install
+## Configuration
 
-```bash
-npm install -g claude-code-memory-explorer
-claude-code-memory-explorer --open
+```
+PORT=8080                Custom port (default: 3544, falls back if busy)
+--dir <path>             Custom Claude config dir (default: ~/.claude)
+--project <path>         Project to inspect (default: current directory)
+--open                   Open browser on start
 ```
 
-## How It Works
-
-Claude Code stores memory across multiple locations:
-
-| Source | Path | Load Behavior |
-|--------|------|---------------|
-| Managed policy | `/etc/claude-code/CLAUDE.md` | Always |
-| User CLAUDE.md | `~/.claude/CLAUDE.md` | Always |
-| Project CLAUDE.md | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Always |
-| CLAUDE.local.md | `./CLAUDE.local.md` | Always |
-| Rules | `.claude/rules/*.md` | Conditional (path-scoped) |
-| Auto memory | `~/.claude/projects/<encoded>/memory/` | Startup (MEMORY.md) or on-demand |
-| Agent memory | `~/.claude/agent-memory/<agent>/`, `./.claude/agent-memory/<agent>/`, `./.claude/agent-memory-local/<agent>/` | Startup (MEMORY.md) or on-demand |
-
-The dashboard:
-1. **Scans** all memory locations — `~/.claude/`, ancestor directories, project rules, auto memory
-2. **Parses** YAML frontmatter in rules files for path globs and metadata
-3. **Resolves** `@import` chains recursively (max 5 levels), tracking both hard imports and soft markdown links
-4. **Groups** sources by scope with parent-child nesting for imports
-5. **Renders** with Highlight.js syntax highlighting — no build step, vanilla JS
-
-Nothing is modified — the dashboard is read-only.
-
-### Memory Path Encoding
-
-Claude Code encodes project paths for auto memory storage: `C:\Users\me\dev\myproject` becomes `C--Users-me-dev-myproject` under `~/.claude/projects/`. The dashboard tries exact match first, then falls back to substring matching.
-
-## FAQ
-
-**Does it modify any files?**
-No. Completely read-only — only reads markdown files from the Claude Code memory locations.
-
-**Does it work with Claude Code Hub?**
-Yes. Exposes `/hub-config` endpoint for hub tab integration.
-
-**Can I switch projects?**
-Yes. Use the project picker (Shift+P) or pass `?project=/path` as a URL parameter.
+The config dir can also be set via the `CLAUDE_CONFIG_DIR` environment variable. Switch projects at runtime with the picker (Shift+P) or `?project=/path`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-memory-explorer",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Memory explorer dashboard for Claude Code",
   "main": "server.js",
   "bin": {

package/public/app.js

@@ -137,7 +137,7 @@ function buildThemeMenu() {
   const menu = document.getElementById('themeMenu');
   menu.innerHTML = COLOR_THEMES.map(
     ([id, label]) =>
-      `<button type="button" class="theme-menu-item" data-theme-id="${id}"
+      `<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}
        </button>`,
@@ -194,6 +194,20 @@ async function loadProject() {
   document.getElementById('projectBtn').title = projectData.path;
 }
 
+// Shared by the project picker, the boot restore, and the hub project shim. Throws with the
+// server's error message so callers can surface it directly.
+async function putProject(dirPath) {
+  const res = await fetch('/api/project', {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: dirPath }),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.error || `${res.status}`);
+  }
+}
+
 function changeProject() {
   const current = document.getElementById('projectBtn').title;
   document.getElementById('projectPathInput').value = current;
@@ -209,20 +223,10 @@ async function submitProjectPicker() {
   btn.disabled = true;
   btn.textContent = 'Switching...';
   try {
-    const res = await fetch('/api/project', {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path: dirPath }),
-    });
-    if (!res.ok) {
-      const err = await res.json();
-      showToast(err.error, 'error');
-      return;
-    }
+    await putProject(dirPath);
     closeModal('projectPickerModal');
     addRecentProject(dirPath);
-    await loadProject();
-    await loadData();
+    await Promise.all([loadProject(), loadData()]);
     showToast('Project switched', 'success');
   } catch (err) {
     showToast(err.message, 'error');
@@ -977,14 +981,24 @@ document.addEventListener('keydown', (e) => {
     .catch(() => ({}));
   if (!cfg.enabled) return;
   window.__HUB__ = cfg;
+  const fwd = (e) =>
+    window.parent?.postMessage(
+      { type: 'hub:keydown', key: e.key, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey },
+      '*',
+    );
   document.addEventListener('keydown', (e) => {
     if (e.ctrlKey && e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
       e.preventDefault();
-      window.parent?.postMessage({ type: 'hub:keydown', key: e.key }, '*');
+      fwd(e);
+    }
+    // Its own branch: the Alt+digit case below requires !ctrlKey.
+    if (e.ctrlKey && e.altKey && !e.shiftKey && !e.metaKey && e.key.toLowerCase() === 'p') {
+      e.preventDefault();
+      fwd(e);
     }
     if (e.altKey && !e.ctrlKey && !e.shiftKey && !e.metaKey && /^[1-9]$/.test(e.key)) {
       e.preventDefault();
-      window.parent?.postMessage({ type: 'hub:keydown', key: e.key }, '*');
+      fwd(e);
     }
   });
 })();
@@ -994,10 +1008,12 @@ function _hubNavigate(app, url) {
   window.parent?.postMessage({ 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);
+
 (function initHubTheme() {
   const getTheme = () => (document.body.classList.contains('light') ? 'light' : 'dark');
   const getColorTheme = () => document.body.dataset.colorTheme || 'ember';
-  const hubOrigin = () => (window.__HUB__?.url ? new URL(window.__HUB__.url).origin : null);
   // 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();
@@ -1028,6 +1044,32 @@ function _hubNavigate(app, url) {
   });
 })();
 
+// 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;
+
+(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;
+    // 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;
+    try {
+      await putProject(dirPath);
+      await Promise.all([loadProject(), loadData()]);
+    } catch (err) {
+      lastApplied = null;
+      console.warn('hub:project failed:', err.message);
+    }
+  });
+})();
+
 // #endregion HUB_INTEGRATION
 
 // #region RESIZE
@@ -1086,16 +1128,21 @@ 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');
-  if (!desiredProject) desiredProject = getRecentProjects()[0] || null;
+  // 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.
+  if (!desiredProject) desiredProject = hubProjectPath || getRecentProjects()[0] || null;
   if (desiredProject) {
     try {
-      const res = await fetch('/api/project', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ path: desiredProject }),
-      });
-      if (!res.ok && params.has('project')) showToast('Failed to switch project', 'error');
-    } catch {}
+      await putProject(desiredProject);
+    } catch {
+      if (params.has('project')) showToast('Failed to switch project', 'error');
+    }
+    // A push that arrived while the PUT above was in flight must still win.
+    if (hubProjectPath && hubProjectPath !== desiredProject) {
+      try {
+        await putProject(hubProjectPath);
+      } catch {}
+    }
   }
   if (params.has('project')) {
     params.delete('project');

package/public/style.css

@@ -202,8 +202,11 @@ body {
   background: var(--bg-hover);
   color: var(--text-primary);
 }
+/* Highlighted with the row's *own* theme accent rather than the active theme's, so the selected
+   row previews the theme it names. --sw-accent comes from the theme-swatch-<id> class on the row. */
 .theme-menu-item.on {
-  color: var(--accent-text);
+  color: var(--sw-accent, var(--accent-text));
+  background: color-mix(in srgb, var(--sw-accent, var(--accent-text)) 16%, transparent);
 }
 /* 3-dot palette preview: surface, accent, ink (colors from themes.css vars) */
 .theme-swatch {

package/server.js

@@ -21,7 +21,7 @@ const expandHome = (p) => (p || '').replace(/^~/, os.homedir());
 
 const PORT = getArg('port') || process.env.PORT || 3544;
 const AUTO_OPEN = process.argv.includes('--open');
-const claudeDirArg = getArg('dir');
+const claudeDirArg = getArg('dir') || process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_DIR;
 const CLAUDE_DIR = claudeDirArg ? expandHome(claudeDirArg) : path.join(os.homedir(), '.claude');
 const projectDirArg = getArg('project');
 
@@ -334,7 +334,7 @@ function discoverMemorySources(projectPath) {
   //    project: <project>/.claude/agent-memory/<agent>/
   //    local:   <project>/.claude/agent-memory-local/<agent>/
   const agentMemoryRoots = [
-    { root: path.join(os.homedir(), '.claude', 'agent-memory'), agentScope: 'user' },
+    { root: path.join(CLAUDE_DIR, 'agent-memory'), agentScope: 'user' },
     { root: path.join(projectPath, '.claude', 'agent-memory'), agentScope: 'project' },
     { root: path.join(projectPath, '.claude', 'agent-memory-local'), agentScope: 'local' },
   ];