From 2c145850c40aa16b2493aec9cb04fe66893b0750 Mon Sep 17 00:00:00 2001
From: Hermes Bot <hermesbot@tellmealex.dev>
Date: Mon, 6 Jul 2026 16:03:17 +0200
Subject: [PATCH] feat(plugin:codebase-memory): dashboard plugin embedding
 local codebase-memory-mcp UI

Adds a new dashboard plugin 'codebase-memory' under plugins/codebase-memory/
that embeds the local codebase-memory-mcp graph UI (DeusData) inside the
existing Hermes dashboard via an iframe. The plugin is intentionally thin:
it draws the chrome (status pill, project picker, open-in-new-tab) and
delegates all graph rendering to the locally running binary at :9749.

Why iframe:
- The codebase-memory-mcp binary ships its own WebGL/canvas renderer;
  reimplementing it would couple the plugin to DeusData's release cadence.
- CORS on :9749 already allows the dashboard origin, so no proxy needed.
- Updates to the upstream UI flow into the dashboard automatically.

Endpoints (auto-mounted at /api/plugins/codebase-memory/):
  /health, /projects, /project/{name}/health, /iframe-url, /open

Config (optional, all keys optional):
  plugins:
    codebase_memory:
      binary_path: ~/.local/bin/codebase-memory-mcp
      ui_port: 9749
      ui_host: 127.0.0.1

Tests: 3 embedded pytests verify imports + endpoint shapes.

Closes #7
---
 plugins/codebase-memory/dashboard/.gitignore  |  11 +
 plugins/codebase-memory/dashboard/README.md   | 119 +++++
 .../codebase-memory/dashboard/dist/index.js   | 494 ++++++++++++++++++
 .../codebase-memory/dashboard/dist/style.css  | 272 ++++++++++
 .../codebase-memory/dashboard/manifest.json   |  15 +
 .../codebase-memory/dashboard/plugin_api.py   | 354 +++++++++++++
 6 files changed, 1265 insertions(+)
 create mode 100644 plugins/codebase-memory/dashboard/.gitignore
 create mode 100644 plugins/codebase-memory/dashboard/README.md
 create mode 100644 plugins/codebase-memory/dashboard/dist/index.js
 create mode 100644 plugins/codebase-memory/dashboard/dist/style.css
 create mode 100644 plugins/codebase-memory/dashboard/manifest.json
 create mode 100644 plugins/codebase-memory/dashboard/plugin_api.py

diff --git a/plugins/codebase-memory/dashboard/.gitignore b/plugins/codebase-memory/dashboard/.gitignore
new file mode 100644
index 000000000000..3cb2f0a9a55c
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/.gitignore
@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.log
+.pytest_cache/
+.coverage
+node_modules/
+.DS_Store
\ No newline at end of file
diff --git a/plugins/codebase-memory/dashboard/README.md b/plugins/codebase-memory/dashboard/README.md
new file mode 100644
index 000000000000..03ea378b02c3
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/README.md
@@ -0,0 +1,119 @@
+# codebase-memory (dashboard plugin)
+
+A native dashboard plugin for Hermes that embeds the local
+[`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp)
+graph UI inside the existing `/codebase-memory` tab. Browse, search and
+explore indexed code repositories without leaving the dashboard.
+
+The plugin is intentionally thin: it draws the chrome (status, project
+picker, open-in-new-tab), and delegates all graph rendering to the
+native codebase-memory-mcp UI via an iframe.
+
+## Architecture
+
+```
+┌─────────── Hermes dashboard (port 9119) ──────────┐
+│ ┌──────────── plugin: codebase-memory ───────────┐ │
+│ │ dist/index.js + style.css (IIFE)               │ │
+│ │ plugin_api.py (FastAPI auto-mounted)           │ │
+│ │   /health, /projects, /project/{n}/health,    │ │
+│ │   /iframe-url, /open                           │ │
+│ └────────────────────────────────────────────────┘ │
+│                       │                             │
+│                       ▼ iframe                      │
+│ ┌──────── codebase-memory-mcp UI (port 9749) ────┐ │
+│ │ WebGL/canvas graph renderer (Cytoscape-free    │ │
+│ │ custom rendering — DeusData)                   │ │
+│ │ + REST + JSON-RPC at /api/* and /rpc           │ │
+│ └────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────┘
+```
+
+We deliberately do **not** re-implement the codebase-memory-mcp graph
+view. DeusData updates their renderer independently and the iframe keeps
+us in sync automatically.
+
+## Configuration
+
+Optional `config.yaml` block:
+
+```yaml
+plugins:
+  codebase_memory:
+    binary_path: ~/.local/bin/codebase-memory-mcp   # default
+    ui_port: 9749                                    # default
+    ui_host: 127.0.0.1                              # default (loopback only)
+```
+
+All keys are optional — the plugin probes `~/.local/bin/codebase-memory-mcp`
+and port 9749 by default.
+
+## Endpoints
+
+| Path                              | Purpose                                         |
+|-----------------------------------|-------------------------------------------------|
+| `GET /api/plugins/codebase-memory/health`              | binary + UI status (always 200) |
+| `GET /api/plugins/codebase-memory/projects`            | list indexed projects (proxied CLI) |
+| `GET /api/plugins/codebase-memory/project/{n}/health`  | per-project node/edge counts |
+| `GET /api/plugins/codebase-memory/iframe-url?project=` | URL for the frontend iframe |
+| `GET /api/plugins/codebase-memory/open?project=`       | URL for "Open in new tab" |
+
+## Operational requirements
+
+1. **Install the binary** (if not already present). Pin to a known release:
+
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/v0.8.1/install.sh | bash
+   ```
+
+   Check the [upstream releases](https://github.com/DeusData/codebase-memory-mcp/releases)
+   for the latest version and update the URL accordingly. We test against
+   `v0.8.1`; the plugin relies only on the stable CLI verbs (`list_projects`,
+   `index_status`, `index_repository`) and the JSON shape of their output.
+
+2. **Bring up the UI server** (the plugin embeds this):
+
+   ```bash
+   codebase-memory-mcp --ui=true --port=9749
+   ```
+
+   The dashboard plugin surfaces this requirement as a help card if the
+   UI is not reachable. The binary's `~/.cache/codebase-memory-mcp/`
+   directory stores the indexed data.
+
+3. **Restart the Hermes dashboard** so it picks up the new plugin directory:
+
+   ```bash
+   pkill -f "hermes dashboard.*--port 9119"
+   cd ~/.hermes/hermes-agent
+   nohup ./venv/bin/hermes dashboard --no-open --port 9119 \
+     > /tmp/dashboard.log 2>&1 &
+   ```
+
+## Verification
+
+`plugin_api.py` embeds three pytest tests at the bottom of the file:
+
+```bash
+pytest plugins/codebase-memory/dashboard/plugin_api.py -v
+```
+
+These verify:
+
+- `test_plugin_self_check` — module imports without side effects
+- `test_health_endpoint_shape` — `/health` returns all documented keys
+- `test_iframe_url_endpoint_shape` — `/iframe-url` returns a valid URL
+
+## Roadmap
+
+- **PR #7** (this one) — iframe wrapper + minimal sidebar
+- **PR #8** — project picker inside the iframe (postMessage bridge with
+  the DeusData UI to select a project without reload)
+- **PR #9** — optional export of indexed nodes to the `mcp_gbrain_*`
+  catalog so the graph shows up alongside the Obsidian vault
+
+## License
+
+MIT (this plugin's source). The embedded UI is the property of DeusData —
+the plugin does not redistribute any of its code; the iframe fetches
+the bundle from the locally running binary at runtime.
\ No newline at end of file
diff --git a/plugins/codebase-memory/dashboard/dist/index.js b/plugins/codebase-memory/dashboard/dist/index.js
new file mode 100644
index 000000000000..07ba1f038d9d
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/dist/index.js
@@ -0,0 +1,494 @@
+/* codebase-memory plugin — dashboard IIFE
+
+This plugin embeds the local codebase-memory-mcp UI (DeusData) inside
+the Hermes dashboard. Layout:
+
+  ┌─────────────────────────────────────────────────────────┐
+  │ Header: status pill + project selector + Open in new tab │
+  ├──────────────┬──────────────────────────────────────────┤
+  │              │                                          │
+  │ Sidebar      │   <iframe src="http://127.0.0.1:9749/">  │
+  │ (projects +  │                                          │
+  │  health +    │   native codebase-memory-mcp UI, full    │
+  │  counts)     │   height, no rebuild needed              │
+  │              │                                          │
+  └──────────────┴──────────────────────────────────────────┘
+
+Why iframe instead of rebuilding the graph view:
+
+  - codebase-memory-mcp ships a fast WebGL/canvas renderer we have
+    no business reimplementing.
+  - DeusData updates the UI independently. The plugin stays in sync
+    automatically.
+  - The CORS headers on :9749 already allow the dashboard origin.
+
+The plugin only owns the chrome around the iframe (project picker,
+status, deep-link). All graph interaction happens inside the iframe.
+*/
+(function () {
+  "use strict";
+
+  var SDK = window.__HERMES_PLUGIN_SDK__;
+  if (!SDK) {
+    console.warn("[codebase-memory] SDK not loaded; plugin disabled");
+    return;
+  }
+  // Hooks + React: this host exposes both `hooks.*` (named) and `React.createElement`.
+  // Use the same pattern as the kanban / achievements plugins.
+  var React = SDK.React;
+  var h = React && React.createElement;
+  var hooks = SDK.hooks || {};
+  var useState = hooks.useState;
+  var useEffect = hooks.useEffect;
+  var useMemo = hooks.useMemo;
+  var useRef = hooks.useRef;
+  var useCallback = hooks.useCallback;
+
+  var fetchJSON = SDK.fetchJSON;
+  var cn = (SDK.utils && SDK.utils.cn) || function () {
+    return Array.prototype.slice.call(arguments).filter(Boolean).join(" ");
+  };
+
+  if (!h || !useState || !useEffect || !useMemo || !useRef) {
+    console.error(
+      "[codebase-memory] missing required SDK surface (React.createElement + hooks)"
+    );
+    return;
+  }
+
+  // ---------------------------------------------------------------------
+  // Sidebar — project list
+  // ---------------------------------------------------------------------
+
+  function ProjectList(props) {
+    var projects = props.projects || [];
+    var selected = props.selected;
+    var onSelect = props.onSelect;
+    var healthByName = props.healthByName || {};
+    var loadingHealth = props.loadingHealth || {};
+
+    if (projects.length === 0) {
+      return h(
+        "div",
+        { className: "hermes-cbm-empty" },
+        "No indexed projects yet. Run ",
+        h("code", null, "codebase-memory-mcp cli index_repository"),
+        " or use the binary's UI to index a repository."
+      );
+    }
+
+    return h(
+      "div",
+      { className: "hermes-cbm-project-list" },
+      projects.map(function (p) {
+        var isActive = selected === p.name;
+        var h = healthByName[p.name];
+        var lh = loadingHealth[p.name];
+        var nodes = h && h.ok ? h.nodes : null;
+        var edges = h && h.ok ? h.edges : null;
+        return h(
+          "button",
+          {
+            key: p.name,
+            className: cn(
+              "hermes-cbm-project",
+              isActive && "hermes-cbm-project--active"
+            ),
+            onClick: function () { onSelect(p.name); },
+          },
+          h(
+            "div",
+            { className: "hermes-cbm-project-name", title: p.root_path || p.name },
+            p.name
+          ),
+          h(
+            "div",
+            { className: "hermes-cbm-project-meta" },
+            lh
+              ? h("span", { className: "hermes-cbm-spinner" }, "…")
+              : nodes != null
+                ? h(
+                    "span",
+                    { className: "hermes-cbm-project-counts" },
+                    nodes.toLocaleString() + " nodes · " +
+                    (edges != null ? edges.toLocaleString() : "?") + " edges"
+                  )
+                : h(
+                    "span",
+                    { className: "hermes-cbm-project-muted" },
+                    "click for stats"
+                  )
+          )
+        );
+      })
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  // Status pill — binary + UI state
+  // ---------------------------------------------------------------------
+
+  function StatusPill(props) {
+    var hs = props.health;
+    if (!hs || hs.state === "loading") {
+        return h(
+          "div",
+          { className: "hermes-cbm-status hermes-cbm-status--unknown" },
+          h("span", { className: "hermes-cbm-status-dot" }),
+          "checking\u2026"
+        );
+      }
+      if (hs.state === "error") {
+        return h(
+          "div",
+          { className: "hermes-cbm-status hermes-cbm-status--error", title: hs.error || "" },
+          h("span", { className: "hermes-cbm-status-dot" }),
+          "dashboard error"
+        );
+      }
+      var d = hs.data || (hs.binary_exists ? { binary_exists: true, ui_base: hs.ui_base, ui_ok: hs.ui_ok } : null);
+      if (!d || !d.binary_exists) {
+        return h(
+          "div",
+          { className: "hermes-cbm-status hermes-cbm-status--error" },
+          h("span", { className: "hermes-cbm-status-dot" }),
+          "binary not found"
+        );
+      }
+      if (!d.ui_ok) {
+        return h(
+          "div",
+          { className: "hermes-cbm-status hermes-cbm-status--warn" },
+          h("span", { className: "hermes-cbm-status-dot" }),
+          "UI not running"
+        );
+      }
+      return h(
+        "div",
+        { className: "hermes-cbm-status hermes-cbm-status--ok" },
+        h("span", { className: "hermes-cbm-status-dot" }),
+        "connected \u00b7 " + d.ui_base
+      );
+    }
+
+  // ---------------------------------------------------------------------
+  // Main page
+  // ---------------------------------------------------------------------
+
+  function CodebaseMemoryPage() {
+    var _health = useState({ state: "loading" });
+    var health = _health[0]; var setHealth = _health[1];
+
+    var _projects = useState({ items: [], state: "loading", error: null });
+    var projectsState = _projects[0]; var setProjectsState = _projects[1];
+    var projects = projectsState.items;
+
+    var _selected = useState(null);
+    var selected = _selected[0]; var setSelected = _selected[1];
+
+    var _iframeUrl = useState(null);
+    var iframeUrl = _iframeUrl[0]; var setIframeUrl = _iframeUrl[1];
+
+    var _healthByName = useState({});
+    var healthByName = _healthByName[0]; var setHealthByName = _healthByName[1];
+
+    var _loadingHealth = useState({});
+    var loadingHealth = _loadingHealth[0]; var setLoadingHealth = _loadingHealth[1];
+
+    var _error = useState(null);
+    var error = _error[0]; var setError = _error[1];
+
+    var iframeRef = useRef(null);
+    var cancelledRef = useRef(false);
+
+    function loadAll() {
+      cancelledRef.current = false;
+      setHealth({ state: "loading" });
+      setProjectsState({ items: [], state: "loading", error: null });
+      setError(null);
+
+      // /health is the source of truth for binary + UI status. Always
+      // resolve it to a structured object — even on failure — so the
+      // status pill can render the right message.
+      fetchJSON("/health")
+        .then(function (h0) {
+          if (cancelledRef.current) return;
+          setHealth({ state: "ok", data: h0 });
+        })
+        .catch(function (e) {
+          if (cancelledRef.current) return;
+          setHealth({ state: "error", error: String(e && e.message || e) });
+        });
+
+      fetchJSON("/projects")
+        .then(function (p0) {
+          if (cancelledRef.current) return;
+          if (p0 && Array.isArray(p0.projects)) {
+            setProjectsState({ items: p0.projects, state: "ok", error: null });
+            if (p0.projects.length > 0 && !selected) {
+              setSelected(p0.projects[0].name);
+            }
+          } else {
+            setProjectsState({ items: [], state: "ok", error: null });
+          }
+        })
+        .catch(function (e) {
+          if (cancelledRef.current) return;
+          setProjectsState({ items: [], state: "error", error: String(e && e.message || e) });
+        });
+    }
+
+    // Initial load: health + project list (in parallel).
+    useEffect(function () {
+      loadAll();
+      return function () { cancelledRef.current = true; };
+    }, []);
+
+    // Whenever the selection changes, update the iframe URL + lazy-fetch health.
+    useEffect(function () {
+      if (!selected) {
+        setIframeUrl(null);
+        return;
+      }
+      fetchJSON("/iframe-url", { params: { project: selected } })
+        .then(function (data) { setIframeUrl(data.url); })
+        .catch(function (e) { setError(String(e)); });
+
+      if (healthByName[selected]) return;
+      setLoadingHealth(function (prev) {
+        var next = Object.assign({}, prev);
+        next[selected] = true;
+        return next;
+      });
+      fetchJSON("/project/" + encodeURIComponent(selected) + "/health")
+        .then(function (data) {
+          setHealthByName(function (prev) {
+            var next = Object.assign({}, prev);
+            next[selected] = data;
+            return next;
+          });
+        })
+        .catch(function () {
+          setHealthByName(function (prev) {
+            var next = Object.assign({}, prev);
+            next[selected] = { ok: false };
+            return next;
+          });
+        })
+        .finally(function () {
+          setLoadingHealth(function (prev) {
+            var next = Object.assign({}, prev);
+            delete next[selected];
+            return next;
+          });
+        });
+    }, [selected]);
+
+    var openInNewTab = useCallback(function () {
+      if (!iframeUrl) return;
+      window.open(iframeUrl, "_blank", "noopener,noreferrer");
+    }, [iframeUrl]);
+
+    var reload = useCallback(function () {
+      if (iframeRef.current && iframeUrl) {
+        // Cache-bust by appending a fresh query param the iframe ignores.
+        var u = iframeUrl + (iframeUrl.indexOf("?") >= 0 ? "&" : "?") +
+                "_t=" + Date.now();
+        iframeRef.current.src = u;
+      }
+    }, [iframeUrl]);
+
+    // ---- Render branches ------------------------------------------------
+
+    if (error && !health) {
+      return h(
+        "div",
+        { className: "hermes-cbm-shell" },
+        h(
+          "div",
+          { className: "hermes-cbm-error" },
+          h("h2", null, "Cannot reach the dashboard backend"),
+          h("p", null, error)
+        )
+      );
+    }
+
+    // Extract binary/UI booleans from the new structured health state.
+    var healthData = health.state === "ok" ? health.data : null;
+    var binaryExists = healthData ? !!healthData.binary_exists : false;
+    var uiOk = healthData ? !!healthData.ui_ok : false;
+
+    return h(
+      "div",
+      { className: "hermes-cbm-shell" },
+
+      // Header
+      h(
+        "div",
+        { className: "hermes-cbm-header" },
+        h(StatusPill, { health: health }),
+        h(
+          "div",
+          { className: "hermes-cbm-header-actions" },
+          h(
+            "button",
+            {
+              className: "hermes-cbm-btn",
+              onClick: reload,
+              disabled: !iframeUrl,
+              title: "Reload the embedded UI",
+            },
+            "Reload"
+          ),
+          h(
+            "button",
+            {
+              className: "hermes-cbm-btn hermes-cbm-btn--primary",
+              onClick: openInNewTab,
+              disabled: !iframeUrl,
+              title: "Open the embedded UI in a new tab",
+            },
+            "Open in new tab"
+          )
+        )
+      ),
+
+      // Body
+      h(
+        "div",
+        { className: "hermes-cbm-body" },
+
+        // Sidebar
+        h(
+          "aside",
+          { className: "hermes-cbm-sidebar" },
+          h(
+            "div",
+            { className: "hermes-cbm-sidebar-title" },
+            "Indexed projects (" + projects.length + ")"
+          ),
+          health.state === "error"
+            ? h(
+                "div",
+                { className: "hermes-cbm-help" },
+                h(
+                  "p",
+                  null,
+                  "Could not reach the plugin backend: ",
+                  h("code", null, health.error || "unknown error"),
+                  ". Try reloading the page — the dashboard rotates its session token on every restart."
+                ),
+                h(
+                  "button",
+                  {
+                    className: "hermes-cbm-btn",
+                    onClick: loadAll,
+                    style: { marginTop: "0.5rem" },
+                  },
+                  "Retry"
+                )
+              )
+            : !binaryExists
+              ? h(
+                  "div",
+                  { className: "hermes-cbm-help" },
+                  h(
+                    "p",
+                    null,
+                    "codebase-memory-mcp is not installed at ",
+                    h("code", null, (healthData && healthData.binary_path) || "~/.local/bin/codebase-memory-mcp"),
+                    ". Install it from ",
+                    h(
+                      "a",
+                      {
+                        href: "https://github.com/DeusData/codebase-memory-mcp",
+                        target: "_blank",
+                        rel: "noopener noreferrer",
+                      },
+                      "github.com/DeusData/codebase-memory-mcp"
+                    ),
+                    ", then restart this dashboard."
+                  ),
+                  h(
+                    "p",
+                    null,
+                    "After install, run ",
+                    h("code", null, "codebase-memory-mcp --ui=true --port=9749"),
+                    " once to bring the embedded UI up."
+                  )
+                )
+              : !uiOk
+                ? h(
+                    "div",
+                    { className: "hermes-cbm-help" },
+                    h(
+                      "p",
+                      null,
+                      "The binary is installed but its UI server is not running. Start it with:"
+                    ),
+                    h(
+                      "pre",
+                      { className: "hermes-cbm-cmd" },
+                      "codebase-memory-mcp --ui=true --port=9749"
+                    )
+                  )
+                : h(ProjectList, {
+                    projects: projects,
+                    selected: selected,
+                    onSelect: setSelected,
+                    healthByName: healthByName,
+                    loadingHealth: loadingHealth,
+                  })
+        ),
+
+        // Main pane (iframe or empty state)
+        h(
+          "main",
+          { className: "hermes-cbm-main" },
+          iframeUrl
+            ? h("iframe", {
+                ref: iframeRef,
+                className: "hermes-cbm-iframe",
+                src: iframeUrl,
+                title: "codebase-memory graph",
+                // sandbox: the codebase-memory-mcp UI runs on the user's
+                // own host at 127.0.0.1:9749 and is trusted (it has
+                // access to the local code graph). We still apply the
+                // standard minimums: scripts same-origin forms popups
+                // popups-to-escape-sandbox are NOT allowed (no
+                // allow-top-navigation, no allow-modals).
+                sandbox: "allow-scripts allow-same-origin allow-forms allow-popups",
+                allow: "clipboard-read; clipboard-write",
+              })
+            : h(
+                "div",
+                { className: "hermes-cbm-empty-main" },
+                projects.length === 0
+                  ? h(
+                      "div",
+                      null,
+                      h("h3", null, "No projects indexed yet"),
+                      h(
+                        "p",
+                        null,
+                        "Use the binary to index a repository, then refresh this page."
+                      )
+                    )
+                  : h(
+                      "div",
+                      null,
+                      h("h3", null, "Pick a project from the sidebar")
+                    )
+              )
+        )
+      )
+    );
+  }
+
+  // Register against the plugin slug. The host maps this to manifest.tab.path.
+  if (window.__HERMES_PLUGINS__ && typeof window.__HERMES_PLUGINS__.register === "function") {
+    window.__HERMES_PLUGINS__.register("codebase-memory", CodebaseMemoryPage);
+  } else {
+    console.warn("[codebase-memory] host __HERMES_PLUGINS__.register missing");
+  }
+})();
\ No newline at end of file
diff --git a/plugins/codebase-memory/dashboard/dist/style.css b/plugins/codebase-memory/dashboard/dist/style.css
new file mode 100644
index 000000000000..f581ed94c192
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/dist/style.css
@@ -0,0 +1,272 @@
+/* codebase-memory plugin — scoped CSS, .hermes-cbm-* prefix.
+   Uses the dashboard's semantic tokens (--bg-card, --text-primary, etc.)
+   so theme switching stays consistent.
+*/
+
+.hermes-cbm-shell {
+  display: flex;
+  flex-direction: column;
+  height: calc(100vh - 4rem);
+  min-height: 480px;
+  background: var(--bg-base);
+  color: var(--text-primary);
+}
+
+/* ----- Header ----- */
+
+.hermes-cbm-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-card);
+  gap: 1rem;
+  flex-shrink: 0;
+}
+
+.hermes-cbm-header-actions {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.hermes-cbm-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.25rem 0.75rem;
+  border-radius: 999px;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  background: var(--bg-card-hover, var(--bg-card));
+  border: 1px solid var(--border);
+}
+
+.hermes-cbm-status-dot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 999px;
+  background: currentColor;
+}
+
+.hermes-cbm-status--ok { color: #4ade80; }
+.hermes-cbm-status--warn { color: #facc15; }
+.hermes-cbm-status--error { color: #f87171; }
+.hermes-cbm-status--unknown { color: var(--text-muted); }
+
+/* ----- Buttons ----- */
+
+.hermes-cbm-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.375rem 0.75rem;
+  border-radius: 0.5rem;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  border: 1px solid var(--border);
+  background: var(--bg-card);
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: background 0.15s ease, border-color 0.15s ease;
+}
+.hermes-cbm-btn:hover:not(:disabled) {
+  background: var(--bg-card-hover, var(--bg-card));
+  border-color: var(--border-hover, var(--border));
+}
+.hermes-cbm-btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.hermes-cbm-btn--primary {
+  background: var(--accent, #60a5fa);
+  color: #0a0a10;
+  border-color: transparent;
+}
+.hermes-cbm-btn--primary:hover:not(:disabled) {
+  filter: brightness(1.08);
+}
+
+/* ----- Body layout (sidebar + iframe) ----- */
+
+.hermes-cbm-body {
+  display: flex;
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.hermes-cbm-sidebar {
+  width: 280px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  background: var(--bg-card);
+  overflow-y: auto;
+  padding: 0.75rem;
+}
+
+.hermes-cbm-sidebar-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  margin-bottom: 0.5rem;
+}
+
+.hermes-cbm-main {
+  flex: 1 1 auto;
+  min-width: 0;
+  background: var(--bg-base);
+  display: flex;
+  flex-direction: column;
+}
+
+/* ----- Project list ----- */
+
+.hermes-cbm-project-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.hermes-cbm-project {
+  text-align: left;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  padding: 0.625rem 0.75rem;
+  border-radius: 0.5rem;
+  background: transparent;
+  border: 1px solid transparent;
+  color: var(--text-primary);
+  cursor: pointer;
+  transition: background 0.12s ease, border-color 0.12s ease;
+}
+.hermes-cbm-project:hover {
+  background: var(--bg-card-hover, var(--bg-card));
+}
+.hermes-cbm-project--active {
+  background: var(--bg-card-hover, var(--bg-card));
+  border-color: var(--accent, #60a5fa);
+}
+
+.hermes-cbm-project-name {
+  font-size: 0.8125rem;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.hermes-cbm-project-meta {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+  min-height: 1.1em;
+}
+
+.hermes-cbm-project-counts {
+  font-variant-numeric: tabular-nums;
+}
+
+.hermes-cbm-project-muted {
+  font-style: italic;
+}
+
+.hermes-cbm-spinner {
+  display: inline-block;
+  animation: hermes-cbm-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes hermes-cbm-pulse {
+  0%, 100% { opacity: 0.4; }
+  50% { opacity: 1; }
+}
+
+/* ----- Empty + help states ----- */
+
+.hermes-cbm-empty {
+  font-size: 0.8125rem;
+  color: var(--text-muted);
+  padding: 1rem 0.5rem;
+  line-height: 1.5;
+}
+.hermes-cbm-empty code {
+  background: var(--bg-base);
+  padding: 0.0625rem 0.3125rem;
+  border-radius: 0.25rem;
+  font-size: 0.75rem;
+}
+
+.hermes-cbm-help {
+  font-size: 0.8125rem;
+  color: var(--text-secondary);
+  padding: 0.5rem 0.25rem;
+  line-height: 1.55;
+}
+.hermes-cbm-help p { margin: 0 0 0.5rem; }
+.hermes-cbm-help a { color: var(--accent, #60a5fa); text-decoration: underline; }
+.hermes-cbm-help code {
+  background: var(--bg-base);
+  padding: 0.0625rem 0.3125rem;
+  border-radius: 0.25rem;
+  font-size: 0.75rem;
+}
+
+.hermes-cbm-cmd {
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: 0.375rem;
+  padding: 0.5rem 0.625rem;
+  font-size: 0.75rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  overflow-x: auto;
+  white-space: pre;
+  margin: 0;
+}
+
+.hermes-cbm-empty-main {
+  flex: 1 1 auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  color: var(--text-muted);
+  padding: 2rem;
+}
+.hermes-cbm-empty-main h3 {
+  margin: 0 0 0.5rem;
+  color: var(--text-primary);
+  font-size: 1rem;
+  font-weight: 600;
+}
+.hermes-cbm-empty-main p { margin: 0; font-size: 0.875rem; }
+
+/* ----- iframe ----- */
+
+.hermes-cbm-iframe {
+  width: 100%;
+  height: 100%;
+  flex: 1 1 auto;
+  border: 0;
+  background: #0a0a10; /* matches the codebase-memory-mcp native dark theme */
+}
+
+/* ----- Errors ----- */
+
+.hermes-cbm-error {
+  margin: 2rem;
+  padding: 1.5rem;
+  border-radius: 0.75rem;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+}
+.hermes-cbm-error h2 {
+  margin: 0 0 0.5rem;
+  color: #f87171;
+  font-size: 1.125rem;
+}
+.hermes-cbm-error p {
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: 0.875rem;
+}
\ No newline at end of file
diff --git a/plugins/codebase-memory/dashboard/manifest.json b/plugins/codebase-memory/dashboard/manifest.json
new file mode 100644
index 000000000000..38aa62e43758
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/manifest.json
@@ -0,0 +1,15 @@
+{
+  "name": "codebase-memory",
+  "label": "Codebase Memory",
+  "icon": "GitBranch",
+  "version": "0.1.0",
+  "description": "Dashboard plugin that embeds the local codebase-memory-mcp graph UI (DeusData) inside Hermes — browse, search, and explore indexed code repositories without leaving the dashboard.",
+  "tab": {
+    "path": "/codebase-memory",
+    "position": "after:knowledge-graph"
+  },
+  "entry": "dist/index.js",
+  "css": "dist/style.css",
+  "api": "plugin_api.py",
+  "permissions": ["api:read"]
+}
\ No newline at end of file
diff --git a/plugins/codebase-memory/dashboard/plugin_api.py b/plugins/codebase-memory/dashboard/plugin_api.py
new file mode 100644
index 000000000000..8163195192bb
--- /dev/null
+++ b/plugins/codebase-memory/dashboard/plugin_api.py
@@ -0,0 +1,354 @@
+"""codebase-memory dashboard plugin — FastAPI router.
+
+This plugin embeds the local `codebase-memory-mcp` UI (DeusData) inside
+the Hermes dashboard. The UI itself runs as a separate process spawned by
+the binary (`~/.local/bin/codebase-memory-mcp --ui=true --port=9749` by
+default) and exposes a single-page web app on that port. The dashboard
+plugin mounts this UI inside an iframe so the user can browse the indexed
+code graph without leaving Hermes.
+
+The plugin's role is intentionally thin:
+
+  - `/health`         checks that the binary is reachable and a UI is
+                      running on the configured port; lists known projects.
+  - `/projects`       calls `codebase-memory-mcp cli list_projects` and
+                      returns the parsed JSON — useful when the JS side
+                      wants to render the project list without parsing
+                      the iframe's internals.
+  - `/project/{name}` returns project health + summary metrics for the
+                      sidebar.
+  - `/iframe-url`     returns the URL the frontend should put in the
+                      iframe (driven by `config.yaml` overrides).
+
+No graph data is proxied through Hermes. All graph queries stay between
+the browser and the codebase-memory-mcp binary over its native REST/JSON-RPC
+channel — the plugin stays out of the way.
+
+Configuration (optional) — see `plugins.codebase_memory.*` in `config.yaml`:
+
+    plugins:
+      codebase_memory:
+        binary_path: ~/.local/bin/codebase-memory-mcp   # default
+        ui_port: 9749                                    # default
+        ui_host: 127.0.0.1                              # default (loopback only)
+
+Verification: pytest block at the bottom (`pytest plugins/codebase-memory/
+dashboard/plugin_api.py -v`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException
+
+router = APIRouter()
+
+PLUGIN_NAME = "codebase-memory"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+def _config() -> dict[str, Any]:
+    """Read `plugins.codebase_memory.*` from the active config.yaml.
+
+    Returns an empty dict on any failure (missing config, malformed YAML,
+    no Hermes home). All consumers of the plugin must tolerate empty config.
+    """
+    candidates: list[Path] = []
+    home = os.environ.get("HERMES_HOME")
+    if home:
+        candidates.append(Path(home) / "config.yaml")
+    candidates.append(Path.home() / ".hermes" / "config.yaml")
+
+    cfg_path: Optional[Path] = None
+    for c in candidates:
+        if c.exists() and c.is_file():
+            cfg_path = c
+            break
+    if cfg_path is None:
+        return {}
+
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return {}
+
+    try:
+        with cfg_path.open("r", encoding="utf-8") as fh:
+            full = yaml.safe_load(fh) or {}
+    except Exception:
+        return {}
+
+    if not isinstance(full, dict):
+        return {}
+    plugins = full.get("plugins") or {}
+    if not isinstance(plugins, dict):
+        return {}
+    cfg = plugins.get(PLUGIN_NAME.replace("-", "_")) or {}
+    if not isinstance(cfg, dict):
+        return {}
+    return cfg
+
+
+def _binary_path() -> str:
+    cfg = _config()
+    raw = cfg.get("binary_path") or "~/.local/bin/codebase-memory-mcp"
+    return os.path.expanduser(str(raw))
+
+
+def _ui_base() -> str:
+    cfg = _config()
+    host = str(cfg.get("ui_host") or "127.0.0.1")
+    port = int(cfg.get("ui_port") or 9749)
+    return f"http://{host}:{port}"
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers
+# ---------------------------------------------------------------------------
+
+def _run_cli(tool: str, payload: Optional[dict[str, Any]] = None,
+             timeout: float = 10.0) -> dict[str, Any]:
+    """Invoke `codebase-memory-mcp cli <tool> '{json}'` and parse JSON.
+
+    Returns a dict with `ok`, plus either `data` (parsed JSON) or `error`
+    (string). Never raises — callers decide whether to surface the error
+    to the frontend or treat the binary as missing.
+
+    The binary writes a one-line `level=info msg=mem.init …` log to stderr
+    before the JSON payload; we strip those log lines and parse the rest.
+    We split on lines and skip any that start with the log prefix
+    `level=` or contain `msg=mem.` rather than scanning for the first
+    brace — this stays robust if a future binary version starts logging
+    multi-line output that contains braces.
+    """
+    binary = _binary_path()
+    if not binary or not Path(binary).exists() and not shutil.which(binary):
+        return {"ok": False, "error": f"binary not found: {binary}"}
+
+    cmd: list[str] = [binary, "cli", tool]
+    if payload is not None:
+        cmd.append(json.dumps(payload))
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "error": f"timeout after {timeout}s"}
+    except FileNotFoundError as exc:
+        return {"ok": False, "error": f"binary not executable: {exc}"}
+    except Exception as exc:
+        return {"ok": False, "error": f"spawn error: {exc}"}
+
+    if proc.returncode != 0:
+        err = (proc.stderr or "").strip() or (proc.stdout or "").strip()
+        return {"ok": False, "error": err or f"exit {proc.returncode}"}
+
+    # Drop structured-log lines the binary emits to stdout (each starts with
+    # `level=`). Whatever remains is the JSON payload.
+    raw = proc.stdout or ""
+    kept = []
+    for line in raw.splitlines():
+        s = line.lstrip()
+        if s.startswith("level=") or "msg=mem." in s:
+            continue
+        kept.append(line)
+    blob = "".join(kept).strip()
+    if not blob.startswith("{"):
+        return {"ok": False, "error": f"no JSON in output: {raw[:200]!r}"}
+    try:
+        data = json.loads(blob)
+    except json.JSONDecodeError as exc:
+        return {"ok": False, "error": f"json parse: {exc} (raw={blob[:200]!r})"}
+    return {"ok": True, "data": data}
+
+
+def _ui_alive(timeout: float = 1.5) -> bool:
+    """Return True if the codebase-memory-mcp UI HTTP server answers."""
+    import urllib.request
+    import urllib.error
+    try:
+        req = urllib.request.Request(_ui_base() + "/", method="GET")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return 200 <= resp.status < 400
+    except (urllib.error.URLError, ConnectionError, TimeoutError, OSError):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@router.get("/health")
+def health() -> dict[str, Any]:
+    """Return plugin + binary + UI status.
+
+    Always 200 (the dashboard polls this for the sidebar badge). The
+    `binary_ok` and `ui_ok` flags tell the frontend which path to render.
+    """
+    binary_path = _binary_path()
+    binary_exists = bool(binary_path) and (Path(binary_path).exists() or shutil.which(binary_path))
+    ui_ok = _ui_alive()
+    started_at = int(time.time())
+    return {
+        "ok": binary_exists,
+        "plugin": PLUGIN_NAME,
+        "version": "0.1.0",
+        "binary_path": binary_path,
+        "binary_exists": binary_exists,
+        "ui_base": _ui_base() if binary_exists else None,
+        "ui_ok": ui_ok,
+        "started_at": started_at,
+    }
+
+
+@router.get("/projects")
+def projects() -> dict[str, Any]:
+    """List projects indexed by the local codebase-memory-mcp instance.
+
+    Proxies `codebase-memory-mcp cli list_projects`. Returns the raw
+    `projects` array plus a `total` count and the `error` field on failure
+    so the frontend can render either the list or a useful empty state.
+    """
+    result = _run_cli("list_projects", timeout=15.0)
+    if not result["ok"]:
+        return {"projects": [], "total": 0, "error": result["error"]}
+    data = result["data"] or {}
+    projects = data.get("projects") or []
+    return {"projects": projects, "total": len(projects), "error": None}
+
+
+@router.get("/project/{name}/health")
+def project_health(name: str) -> dict[str, Any]:
+    """Forward `index_status` for a specific project (with a friendly alias).
+
+    The binary accepts the qualified project name; we forward `name` as-is
+    after URL-decoding. Errors come back as `error` strings — never as
+    5xx — so the sidebar can show a per-project health badge.
+    """
+    # The binary's CLI doesn't have a direct "health" subcommand, but
+    # `index_status` returns the same shape with optional project filter.
+    result = _run_cli("index_status", {"project": name}, timeout=10.0)
+    if not result["ok"]:
+        return {"name": name, "ok": False, "error": result["error"]}
+    data = result["data"] or {}
+    return {
+        "name": name,
+        "ok": True,
+        "nodes": data.get("total_nodes"),
+        "edges": data.get("total_edges"),
+        "node_labels": data.get("node_labels"),
+        "languages": data.get("languages"),
+        "size_bytes": data.get("size_bytes"),
+    }
+
+
+@router.get("/iframe-url")
+def iframe_url(project: Optional[str] = None) -> dict[str, Any]:
+    """Return the URL the frontend should load inside the iframe.
+
+    The codebase-memory-mcp UI is a single-page app at the root. Project
+    selection is passed as a query string for forward-compat (the bundle
+    currently ignores it but reserves the parameter for the project
+    picker in the binary's own UI).
+    """
+    base = _ui_base()
+    if not project:
+        return {"url": base + "/", "project": None}
+    from urllib.parse import urlencode
+    qs = urlencode({"project": project})
+    return {"url": f"{base}/?{qs}", "project": project}
+
+
+@router.get("/open")
+def open_in_browser(project: Optional[str] = None) -> dict[str, Any]:
+    """Return a hint to the frontend with the URL.
+
+    Kept as an endpoint rather than auto-opening because the dashboard's
+    auth context shouldn't leak outside its iframe sandbox. The frontend
+    uses this to render the "Open in new tab" button on the toolbar.
+    """
+    return iframe_url(project)
+
+
+# ---------------------------------------------------------------------------
+# Tests (pytest embedded in plugin_api.py — same pattern as knowledge-graph)
+# ---------------------------------------------------------------------------
+
+def _self_test_imports() -> bool:
+    """Lightweight check that the module imports without side effects."""
+    try:
+        import importlib
+        m = importlib.import_module(__name__)
+        return hasattr(m, "router") and hasattr(m, "PLUGIN_NAME")
+    except Exception:
+        return False
+
+
+def _self_test_health_shape() -> bool:
+    """`health()` returns the documented keys even when the binary is missing."""
+    import urllib.request
+    import urllib.error
+    try:
+        # We can't call the running router from a unit test, but we can
+        # sanity-check the response keys by invoking the helpers directly.
+        from fastapi.testclient import TestClient
+        from fastapi import FastAPI
+        app = FastAPI()
+        app.include_router(router)
+        with TestClient(app) as client:
+            r = client.get("/health")
+            body = r.json()
+            for key in ("ok", "plugin", "version", "binary_path",
+                        "binary_exists", "ui_base", "ui_ok", "started_at"):
+                if key not in body:
+                    return False
+        return True
+    except (ImportError, urllib.error.URLError, AssertionError, Exception):
+        return False
+
+
+def _self_test_iframe_url_shape() -> bool:
+    """`/iframe-url` returns a `url` key that points at the configured UI base."""
+    from fastapi.testclient import TestClient
+    from fastapi import FastAPI
+    app = FastAPI()
+    app.include_router(router)
+    with TestClient(app) as client:
+        r1 = client.get("/iframe-url")
+        r2 = client.get("/iframe-url", params={"project": "demo"})
+        if "url" not in r1.json() or "url" not in r2.json():
+            return False
+        if not r1.json()["url"].startswith("http://"):
+            return False
+        if "project=demo" not in r2.json()["url"]:
+            return False
+    return True
+
+
+# These tests are picked up by pytest when the file is collected (the
+# knowledge-graph plugin follows the same convention — no separate test
+# file, so the plugin is self-contained).
+def test_plugin_self_check():
+    assert _self_test_imports()
+
+
+def test_health_endpoint_shape():
+    assert _self_test_health_shape()
+
+
+def test_iframe_url_endpoint_shape():
+    assert _self_test_iframe_url_shape()
\ No newline at end of file