claude-code-memory-explorer 0.1.0

package/.claude/commands/release.md

@@ -0,0 +1,54 @@
+---
+description: Bump version, tag, push, and create a GitHub release with auto-generated notes
+argument-hint: "[version e.g. 1.13.0 or rc4]"
+---
+
+# Release
+
+Create a new release for this project.
+
+## Inputs
+
+- `$ARGUMENTS` — target version or shorthand. Examples:
+  - `1.13.0` — full version
+  - `rc4` — shorthand for next RC (e.g. if current is `1.19.0-rc.3`, becomes `1.19.0-rc.4`)
+  - If not provided, ask the user.
+
+## Steps
+
+1. **Determine version**: Use `$ARGUMENTS` or ask user. Handle `rc<N>` shorthand by reading current version from `package.json` and replacing/appending the RC suffix. Validate it's different from the current version.
+
+2. **Detect prerelease**: If version contains `-rc.`, `-alpha.`, `-beta.`, treat as prerelease.
+
+3. **Check working tree**: Run `git status`. If there are uncommitted changes, warn the user and stop.
+
+4. **Bump version**:
+   ```
+   npm version <version> --no-git-tag-version
+   ```
+
+5. **Commit & push** (push to current branch, not hardcoded `main`):
+   ```
+   git add package.json package-lock.json
+   git commit -m "🔖 chore: Bump version to <version>"
+   git push origin HEAD
+   ```
+
+6. **Tag & push tag**:
+   ```
+   git tag v<version>
+   git push origin v<version>
+   ```
+
+7. **Generate release notes**: Collect commits since the previous tag using `git log --oneline <prev-tag>..HEAD`. Write a **user-facing summary** grouped by:
+   - Features (✨) — describe what was added, not raw commit messages
+   - Fixes (🐛)
+   - Other notable changes
+   Include a "Full Changelog" compare link at the bottom.
+
+8. **Create GitHub release** (add `--prerelease` flag for RC/alpha/beta):
+   ```
+   gh release create v<version> --title "v<version>" --notes "<notes>" [--prerelease]
+   ```
+
+9. **Report**: Show the release URL to the user.

package/.github/workflows/pages.yml

@@ -0,0 +1,36 @@
+name: Deploy static site to Pages
+
+on:
+  push:
+    branches: ["main", "master"]
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "docs"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Dashboard for visualizing all memory sources that influence Claude Code behavior. Shows the full memory stack: CLAUDE.md files (user/project/local), rules (`.claude/rules/*.md` with optional path-scoped frontmatter), auto memory (`~/.claude/projects/<encoded>/memory/`), and `@import` chains.
+
+## Commands
+
+- `npm start` — run server (port 3459)
+- `npm run dev` — run with auto-open browser
+- `npx @biomejs/biome check public/app.js public/style.css` — lint
+- `npx @biomejs/biome format --write public/app.js public/style.css` — format
+
+## Architecture
+
+Single-file Express backend + vanilla JS frontend. No build step, no framework.
+
+- **`server.js`** — Express server with two main responsibilities:
+  1. **Filesystem scanning** (`discoverMemorySources`) — walks `~/.claude/`, ancestor directories, project `.claude/rules/`, and auto memory dirs to build the full memory source stack
+  2. **API endpoints** — `/api/stack`, `/api/summary`, `/api/file`, `/api/rules/match`, `/api/imports` etc.
+- **`public/app.js`** — SPA with tree panel (left) + preview panel (right) split layout. Fetches from API, renders tree grouped by scope, shows syntax-highlighted preview with frontmatter badges and clickable `@import` links.
+- **`public/style.css`** — CSS variables on `:root` (dark default), `body.light` overrides. Scope colors: user=blue, project=green, local=yellow, rule=purple, memory=orange, policy=red.
+
+Both JS files use `// #region` / `// #endregion` markers for code organization.
+
+## Key Server Concepts
+
+- **Project path encoding**: Claude Code stores auto memory in `~/.claude/projects/<encoded-path>/memory/`. The encoding replaces `/` with `-` and strips `:` from drive letters. `findMemoryDir()` tries exact match first, falls back to substring matching.
+- **Import resolution**: `@path/to/file.md` references are parsed from content. `resolveExistingImports()` resolves paths and filters out non-existent files. Imported files are recursively added to the stack (max 5 levels).
+- **Frontmatter parsing**: YAML frontmatter in rules files (`paths`, `type`, `name`, `description`) determines conditional loading. `parseFrontmatter()` handles both inline values and YAML array syntax.
+- **Rules matching**: `micromatch` glob matching against rule `paths` frontmatter via `/api/rules/match?file=`.
+- **Cache**: 30-second TTL on `discoverMemorySources` results, cleared on project switch or manual refresh.
+
+## Conventions
+
+- Dark theme default, light theme via `body.light` class
+- Accent color: `#e86f33`
+- Fonts: IBM Plex Mono (data/code), Playfair Display (headings)
+- Keyboard-driven: j/k navigation, t=theme, r=refresh, e=open in editor, ?=help
+- Port 3459 (cost=3458, marketplace=3460)
+- `zoom: 1.25` on body for proportional scaling
+- No token/context budget estimation — only line/byte counts (deliberate decision)
+
+## Prior Art
+
+- `../claude-code-cost` — same stack, data visualization patterns
+- `../claude-code-marketplace` — file tree, markdown preview, project picker, Highlight.js usage

package/README.md

@@ -0,0 +1,92 @@
+# Claude Code Memory
+
+[![npm version](https://img.shields.io/npm/v/claude-code-memory-explorer)](https://www.npmjs.com/package/claude-code-memory-explorer)
+[![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.
+
+## Getting Started
+
+```bash
+npx claude-code-memory-explorer --open
+```
+
+Open http://localhost:3459 (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)
+
+## 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
+
+## Configuration
+
+```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
+```
+
+If port 3459 is in use, the server falls back to a random available port.
+
+### Global install
+
+```bash
+npm install -g claude-code-memory-explorer
+claude-code-memory-explorer --open
+```
+
+## 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 |
+
+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.
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "style": {
+        "noDescendingSpecificity": "off"
+      },
+      "suspicious": {
+        "useIterableCallbackReturn": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "css": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "files": {
+    "includes": ["public/app.js", "public/style.css"]
+  }
+}