fix(claude): honor CLAUDE_CONFIG_DIR for user-scope MCP config and the plugin cache

The CLI relocates .claude.json to $CLAUDE_CONFIG_DIR/.claude.json when
the override is set, but the MCP manager kept reading (and writing
disabledMcpServers to) $HOME/.claude.json while CLI-mediated writes via
'claude mcp add' inherited the env and landed in the relocated file, so
reads and writes diverged on override deployments. The plugin cache
fallback similarly pointed at ~/.claude/plugins instead of the relocated
cache.

The .claude.json resolver is a private helper rather than a reuse of
util.get_claude_config_dir because its default genuinely differs: the
file lives in the home dir itself, not inside ~/.claude. The plugins
fallback does route through the shared helper; the CLI gives
CLAUDE_CODE_PLUGIN_CACHE_DIR precedence over the config dir and NBI
matches that, verified against the CLI bundle and a sandboxed
'claude mcp add' run.

Test hardening that the change made necessary: the unittest-style PATCH
suite patches Path.home but pytest fixtures don't reach it, so a
developer's exported CLAUDE_CONFIG_DIR would have sent the endpoint's
write into their real relocated .claude.json; setUp now snapshots and
scrubs the env. The Playwright webServer env drops the variable for the
same reason, deleting it rather than blanking it because the CLI treats
an empty string as a set (degenerate) config dir.

Also dates 5.1.0 in the changelog (released 2026-06-08) and adds the
missing compare links.

Fixes #375

Author: pjdoland

CHANGELOG.md

@@ -13,8 +13,9 @@ For each release we list user-facing changes grouped as **Added**, **Changed**,
 ### Fixed
 
 - **Session history follows `CLAUDE_CONFIG_DIR`** (#373). The chat-sidebar resume picker and the launcher tile's session list always read transcripts from `~/.claude/projects`, so both came up empty when the Claude CLI was configured with `CLAUDE_CONFIG_DIR` and wrote its transcripts elsewhere. The session listing now resolves the CLI's config dir the same way the skills and spinner-verbs paths already did.
+- **User-scope MCP config and the plugin cache follow `CLAUDE_CONFIG_DIR`** (#375). The MCP management tab read user-scope servers from `~/.claude.json` even though the CLI relocates that file to `$CLAUDE_CONFIG_DIR/.claude.json` when the override is set (so reads and CLI-mediated writes diverged), and the Plugins panel's cache fallback pointed at `~/.claude/plugins` instead of the relocated cache. Both now resolve the CLI's actual locations; `CLAUDE_CODE_PLUGIN_CACHE_DIR` still wins for the plugin cache when set.
 
-## [5.1.0] - UNRELEASED
+## [5.1.0] - 2026-06-08
 
 5.1.0 builds on 5.0.x with a focus on Claude-mode agent visibility. Tool calls the agent runs now render as persistent status cards with inline diffs and collapsible grouping, the generating indicator can cycle custom verbs, and cancelling a turn tears down the whole process tree the agent spawned instead of leaking it. It also adds two opt-in security guardrails (an MCP stdio-command allowlist and a default-token-password check on shared filesystems) and an always-visible mode for chat feedback. No traitlet, env-var, REST route, or on-disk-format renames or removals; every new admin surface is opt-in and listed below.
 
@@ -378,7 +379,8 @@ A multi-PR accessibility pass landed across most NBI surfaces. Together these ma
 - Settings UI restructured around Claude vs default mode.
 - WebSocket connection reliability improvements.
 
-[unreleased]: https://github.com/plmbr/notebook-intelligence/compare/v5.0.1...HEAD
+[unreleased]: https://github.com/plmbr/notebook-intelligence/compare/v5.1.0...HEAD
+[5.1.0]: https://github.com/plmbr/notebook-intelligence/compare/v5.0.1...v5.1.0
 [5.0.1]: https://github.com/plmbr/notebook-intelligence/compare/v5.0.0...v5.0.1
 [5.0.0]: https://github.com/plmbr/notebook-intelligence/compare/v4.8.0...v5.0.0
 [4.8.0]: https://github.com/plmbr/notebook-intelligence/compare/v4.7.0...v4.8.0

docs/admin-guide.md

@@ -57,7 +57,7 @@ Manual edits to `config.json` while JupyterLab is running require a JupyterLab r
 | `<env-prefix>/share/jupyter/nbi/`         | No (image)  | Org-wide base config. Bake into your container image.                                                                                                                                                                                               |
 | Project-scope `<project>/.claude/skills/` | Per project | Lives in the user's working directory. Persists if the working directory does.                                                                                                                                                                      |
 
-For Kubeflow or KubeSpawner: mount the user's home directory on a PVC and ensure `~/.jupyter` and `~/.claude` are inside that mount. Anything else (`/tmp`, `~/.cache`) can be ephemeral.
+For Kubeflow or KubeSpawner: mount the user's home directory on a PVC and ensure `~/.jupyter` and `~/.claude` are inside that mount (or `$CLAUDE_CONFIG_DIR`, if you point the Claude CLI elsewhere). Anything else (`/tmp`, `~/.cache`) can be ephemeral.
 
 ---
 
@@ -473,7 +473,7 @@ Force-off:
 - Hides the Claude-mode **MCP Servers** tab in the Settings panel (visible only when Claude mode is on and the `claude` CLI is available).
 - Returns HTTP 403 from every `/notebook-intelligence/claude-mcp/*` route.
 
-The Claude-mode tab is **independent** of the existing non-Claude **MCP Servers** tab. The former wraps Claude Code's own config (`~/.claude.json` and project `.mcp.json`); the latter manages NBI's own MCP servers used by the non-Claude chat path. They never appear at the same time — the non-Claude tab is hidden when Claude mode is on, and the Claude-mode tab is hidden when it's off.
+The Claude-mode tab is **independent** of the existing non-Claude **MCP Servers** tab. The former wraps Claude Code's own config (`~/.claude.json`, relocated to `$CLAUDE_CONFIG_DIR/.claude.json` when that env var is set, and project `.mcp.json`); the latter manages NBI's own MCP servers used by the non-Claude chat path. They never appear at the same time; the non-Claude tab is hidden when Claude mode is on, and the Claude-mode tab is hidden when it's off.
 
 Reads come from Claude's JSON config files directly (fast, no health checks). Writes (add / remove) shell out to `claude mcp add` / `claude mcp remove` so Claude remains the source of truth for any side effects (project-trust prompts, OAuth bookkeeping).
 
@@ -515,7 +515,7 @@ c.NotebookIntelligence.claude_plugins_management_policy = "force-off"
 
 Or via env: `NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY=force-off`.
 
-Force-off hides the **Plugins** tab and returns 403 from every `/notebook-intelligence/plugins/*` route. The tab is otherwise visible only when Claude mode is on and the `claude` CLI is available. Both reads (`claude plugin list --json`) and writes (`claude plugin install` / `uninstall` / `enable` / `disable` / `marketplace add` / `marketplace remove`) shell out to the Claude CLI; Claude owns the plugin state under `~/.claude/plugins/`.
+Force-off hides the **Plugins** tab and returns 403 from every `/notebook-intelligence/plugins/*` route. The tab is otherwise visible only when Claude mode is on and the `claude` CLI is available. Both reads (`claude plugin list --json`) and writes (`claude plugin install` / `uninstall` / `enable` / `disable` / `marketplace add` / `marketplace remove`) shell out to the Claude CLI; Claude owns the plugin state under `~/.claude/plugins/` (`$CLAUDE_CONFIG_DIR/plugins/` when that env var is set); NBI reads the same location.
 
 > **Blast radius.** Force-off only kills the _management UI_ — already-installed plugins keep loading inside Claude Code sessions because Claude's plugin loader doesn't consult NBI's policy. To stop existing plugins from loading, you'd need to remove them on disk or disable them via the `claude plugin disable` CLI before flipping the policy. Force-off prevents user-driven add/remove/enable/disable through NBI; that's the contract.
 

notebook_intelligence/claude_mcp_manager.py

@@ -8,6 +8,9 @@
   - Local scope:   ``~/.claude.json`` → ``projects.<cwd>.mcpServers``
   - Project scope: ``<cwd>/.mcp.json``
 
+When ``CLAUDE_CONFIG_DIR`` is set, the CLI relocates ``.claude.json`` to
+``$CLAUDE_CONFIG_DIR/.claude.json`` and the reads follow it there.
+
 Writes go through ``claude mcp add`` / ``claude mcp remove`` so Claude
 remains the source of truth for any side effects (project-trust prompts,
 oauth bookkeeping, etc.). The file-based reads are decoupled from the CLI's
@@ -21,6 +24,7 @@
 import dataclasses
 import json
 import logging
+import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Iterable, Literal, Optional
@@ -127,6 +131,21 @@ def _gather_from_dict(
     return out
 
 
+def _claude_user_config_path() -> Path:
+    """Locate the CLI's ``.claude.json``.
+
+    Unlike skills and transcripts, the default lives in the home dir itself
+    rather than inside ``~/.claude``, so this can't reuse
+    ``util.get_claude_config_dir``'s fallback: the CLI keeps the file at
+    ``$HOME/.claude.json`` normally but relocates it to
+    ``$CLAUDE_CONFIG_DIR/.claude.json`` when the override is set.
+    """
+    override = os.environ.get("CLAUDE_CONFIG_DIR")
+    if override:
+        return Path(override) / ".claude.json"
+    return Path.home() / ".claude.json"
+
+
 class ClaudeMCPManager:
     # Class-level so the lock is shared across all ClaudeMCPManager instances
     # within this process. Handlers construct a fresh manager per request,
@@ -142,7 +161,7 @@ def __init__(
         stdio_command_allowlist: Optional[Iterable[str]] = None,
     ):
         self._working_dir = Path(working_dir) if working_dir else Path.cwd()
-        self._user_config_path = Path.home() / ".claude.json"
+        self._user_config_path = _claude_user_config_path()
         # An empty allowlist means "no enforcement"; the default keeps
         # per-user deployments permissive. Admins thread their pinned
         # regex list in via ``stdio_command_allowlist``.

notebook_intelligence/plugin_manager.py

@@ -2,7 +2,8 @@
 
 """Wrapper around Claude Code's `claude plugin` CLI.
 
-Plugin state is owned by Claude Code itself (under `~/.claude/plugins/`).
+Plugin state is owned by Claude Code itself (under `~/.claude/plugins/`,
+or `$CLAUDE_CONFIG_DIR/plugins/` when that env var is set).
 NBI shells out for both reads and writes:
 
   - `claude plugin list --json` → JSON array of installed plugins
@@ -35,7 +36,7 @@
     run_claude_cli,
     validate_scope,
 )
-from notebook_intelligence.util import resolve_github_token
+from notebook_intelligence.util import get_claude_config_dir, resolve_github_token
 
 log = logging.getLogger(__name__)
 
@@ -244,7 +245,7 @@ def _claude_plugins_root() -> Path:
     configured = os.environ.get(CLAUDE_PLUGIN_CACHE_DIR_ENV)
     if configured:
         return Path(configured).expanduser()
-    return Path.home() / ".claude" / "plugins"
+    return Path(get_claude_config_dir()) / "plugins"
 
 
 def _validate_marketplace_name(name: str) -> str:

tests/test_claude_mcp_manager.py

@@ -4,6 +4,7 @@
 
 import asyncio
 import json
+import os
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
@@ -28,6 +29,9 @@ def claude_home(tmp_path, monkeypatch):
     home = tmp_path / "home"
     home.mkdir()
     monkeypatch.setattr(Path, "home", classmethod(lambda cls: home))
+    # A developer's exported CLAUDE_CONFIG_DIR would otherwise bypass the
+    # Path.home seam now that the manager honors the override.
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
     return home
 
 
@@ -832,12 +836,20 @@ def setUp(self):
             Path, "home", classmethod(lambda cls: self._home)
         )
         self._home_patcher.start()
+        # unittest-style classes don't get the claude_home fixture's delenv;
+        # without this, an exported CLAUDE_CONFIG_DIR bypasses the Path.home
+        # seam and the PATCH writes into the developer's real relocated
+        # .claude.json.
+        self._env_patcher = patch.dict(os.environ)
+        self._env_patcher.start()
+        os.environ.pop("CLAUDE_CONFIG_DIR", None)
         self._cwd_patcher = patch.object(
             ext_module, "get_jupyter_root_dir", lambda: str(self._cwd)
         )
         self._cwd_patcher.start()
 
     def tearDown(self):
+        self._env_patcher.stop()
         self._home_patcher.stop()
         self._cwd_patcher.stop()
         import shutil
@@ -896,3 +908,56 @@ def test_patch_rejects_missing_field(self):
         response = self._fetch_patch("/claude-mcp/user/voicemode", {})
         assert response.code == 400
         assert b"Missing" in response.body
+
+
+class TestClaudeUserConfigPath:
+    """`.claude.json` must follow CLAUDE_CONFIG_DIR (issue #375).
+
+    The CLI keeps the file at $HOME/.claude.json by default but relocates
+    it to $CLAUDE_CONFIG_DIR/.claude.json when the override is set, so a
+    manager reading the home path on an override deployment sees stale or
+    missing user-scope servers.
+    """
+
+    def test_reads_relocated_config_when_override_set(
+        self, tmp_path, working_dir, monkeypatch
+    ):
+        override = tmp_path / "workspace" / ".claude"
+        override.mkdir(parents=True)
+        (override / ".claude.json").write_text(
+            json.dumps(
+                {
+                    "mcpServers": {
+                        "relocated": {
+                            "type": "http",
+                            "url": "https://example.com/mcp",
+                        }
+                    }
+                }
+            ),
+            encoding="utf-8",
+        )
+        monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(override))
+
+        manager = ClaudeMCPManager(working_dir=str(working_dir))
+
+        assert [s.name for s in manager.list_servers()] == ["relocated"]
+
+    def test_override_wins_over_home_config(
+        self, claude_home, working_dir, monkeypatch, tmp_path
+    ):
+        _write_claude_json(
+            claude_home,
+            {"mcpServers": {"home-srv": {"type": "http", "url": "https://h"}}},
+        )
+        override = tmp_path / "workspace" / ".claude"
+        override.mkdir(parents=True)
+        monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(override))
+
+        manager = ClaudeMCPManager(working_dir=str(working_dir))
+
+        assert manager.list_servers() == []
+
+    def test_defaults_to_home_when_unset(self, claude_home, working_dir):
+        manager = ClaudeMCPManager(working_dir=str(working_dir))
+        assert manager._user_config_path == claude_home / ".claude.json"

tests/test_plugin_manager.py

@@ -15,6 +15,7 @@
 from notebook_intelligence._claude_cli import redact_argv_for_log
 from notebook_intelligence.plugin_manager import (
     PluginManager,
+    _claude_plugins_root,
     is_acceptable_marketplace_source,
     is_github_marketplace_source,
 )
@@ -1241,3 +1242,29 @@ def test_passes_through_non_secret_flags(self):
 # Per-family policy-gate coverage lives in `tests/test_policy_gate.py`,
 # parametrized across SkillsBaseHandler / ClaudeMCPBaseHandler /
 # PluginsBaseHandler.
+
+
+class TestClaudePluginsRoot:
+    """The plugins-root fallback must follow CLAUDE_CONFIG_DIR (issue #375).
+
+    The CLI keeps its plugin cache under the config dir, so when
+    CLAUDE_CONFIG_DIR is set (and no explicit cache-dir override exists)
+    the root is $CLAUDE_CONFIG_DIR/plugins, not ~/.claude/plugins.
+    """
+
+    def test_falls_back_to_claude_config_dir(self, tmp_path, monkeypatch):
+        monkeypatch.delenv("CLAUDE_CODE_PLUGIN_CACHE_DIR", raising=False)
+        monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "cfg"))
+        assert _claude_plugins_root() == tmp_path / "cfg" / "plugins"
+
+    def test_explicit_cache_dir_wins_over_config_dir(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("CLAUDE_CODE_PLUGIN_CACHE_DIR", str(tmp_path / "cache"))
+        monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "cfg"))
+        assert _claude_plugins_root() == tmp_path / "cache"
+
+    def test_defaults_to_home_claude_plugins(self, tmp_path, monkeypatch):
+        monkeypatch.delenv("CLAUDE_CODE_PLUGIN_CACHE_DIR", raising=False)
+        monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path))
+        assert _claude_plugins_root() == tmp_path / ".claude" / "plugins"

ui-tests/playwright.config.ts

@@ -8,6 +8,12 @@
 // its own; import the config helper from `@playwright/test` directly.
 import { defineConfig, devices } from '@playwright/test';
 
+const webServerEnv: { [key: string]: string } = Object.fromEntries(
+  Object.entries(process.env).filter(
+    ([key, value]) => key !== 'CLAUDE_CONFIG_DIR' && value !== undefined
+  )
+) as { [key: string]: string };
+
 export default defineConfig({
   // Tests live next to this config so they can ``import { test, expect } from
   // '@jupyterlab/galata'`` without long relative paths.
@@ -23,7 +29,14 @@ export default defineConfig({
     command: 'jlpm start',
     url: 'http://localhost:8888/lab',
     timeout: 120_000,
-    reuseExistingServer: !process.env.CI
+    reuseExistingServer: !process.env.CI,
+    // The MCP PATCH spec relies on HOME isolation to keep writes out of the
+    // developer's real ~/.claude.json; an exported CLAUDE_CONFIG_DIR would
+    // bypass that seam (the server follows the override), so drop it. Delete
+    // rather than set to '': the claude CLI treats an empty string as a set
+    // (and degenerate) config dir, so '' would only cover the server's own
+    // file reads, not any future spec that shells out to the CLI.
+    env: webServerEnv
   },
 
   use: {

ui-tests/tests/claude-mcp-patch.spec.ts

@@ -12,7 +12,9 @@
  * Requires HOME to point at an isolated directory the test owns; otherwise
  * the PATCH would mutate the user's real ~/.claude.json. The runner sets
  * HOME=/tmp/... before invoking jlpm playwright, and the seed file is
- * placed by the test itself before each run.
+ * placed by the test itself before each run. CLAUDE_CONFIG_DIR must not
+ * leak into the server env (the server follows the override, bypassing
+ * the HOME seam); playwright.config.ts drops it from the webServer env.
  */
 import { expect, test } from '@jupyterlab/galata';