claudeup 4.12.0 → 4.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",

package/src/prerunner/index.js

@@ -4,92 +4,10 @@ import os from "node:os";
 import { UpdateCache } from "../services/update-cache.js";
 import { getAvailablePlugins, clearMarketplaceCache, } from "../services/plugin-manager.js";
 import { runClaude } from "../services/claude-runner.js";
-import { recoverMarketplaceSettings, migrateMarketplaceRename, cleanupExtraKnownMarketplaces, getGlobalEnabledPlugins, getEnabledPlugins, getLocalEnabledPlugins, readGlobalSettings, writeGlobalSettings, saveGlobalInstalledPluginVersion, gapFillInstalledPluginVersions, } from "../services/claude-settings.js";
+import { recoverMarketplaceSettings, migrateMarketplaceRename, cleanupExtraKnownMarketplaces, readGlobalSettings, writeGlobalSettings, saveGlobalInstalledPluginVersion, gapFillInstalledPluginVersions, } from "../services/claude-settings.js";
 import { checkPluginVersionMismatches, formatMismatchWarning, } from "../services/plugin-version-check.js";
-import { parsePluginId } from "../utils/string-utils.js";
-import { defaultMarketplaces } from "../data/marketplaces.js";
-import { updatePlugin, addMarketplace, isClaudeAvailable, } from "../services/claude-cli.js";
-const MARKETPLACES_DIR = path.join(os.homedir(), ".claude", "plugins", "marketplaces");
-/**
- * Collect all unique marketplace names from enabled plugins across all settings scopes.
- * Returns a Set of marketplace names (e.g., "magus", "claude-plugins-official").
- */
-async function getReferencedMarketplaces(projectPath) {
-    const marketplaceNames = new Set();
-    // Collect plugin IDs from all scopes
-    const allPluginIds = new Set();
-    try {
-        const global = await getGlobalEnabledPlugins();
-        for (const id of Object.keys(global))
-            allPluginIds.add(id);
-    }
-    catch {
-        /* skip if unreadable */
-    }
-    if (projectPath) {
-        try {
-            const project = await getEnabledPlugins(projectPath);
-            for (const id of Object.keys(project))
-                allPluginIds.add(id);
-        }
-        catch {
-            /* skip if unreadable */
-        }
-        try {
-            const local = await getLocalEnabledPlugins(projectPath);
-            for (const id of Object.keys(local))
-                allPluginIds.add(id);
-        }
-        catch {
-            /* skip if unreadable */
-        }
-    }
-    // Parse marketplace names from plugin IDs
-    for (const pluginId of allPluginIds) {
-        const parsed = parsePluginId(pluginId);
-        if (parsed) {
-            marketplaceNames.add(parsed.marketplace);
-        }
-    }
-    return marketplaceNames;
-}
-/**
- * Check which referenced marketplaces are missing locally and auto-add them.
- * Only adds marketplaces with known repos (from defaultMarketplaces).
- *
- * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
- * Claude Code's `marketplace update` calls cacheMarketplaceFromGit() which
- * deletes the marketplace directory before re-cloning. If the clone fails
- * (network timeout, auth error), the directory stays permanently deleted
- * and ALL plugins from that marketplace break. See:
- * ai-docs/plugin-marketplace-bug-investigation.md
- *
- * Claude Code's own background autoupdate handles marketplace refreshing
- * after session start — claudeup should only recover genuinely missing
- * marketplaces, not trigger additional refresh cycles.
- */
-async function autoAddMissingMarketplaces(projectPath) {
-    const referenced = await getReferencedMarketplaces(projectPath);
-    const added = [];
-    for (const mpName of referenced) {
-        // Check if marketplace directory exists locally
-        const mpDir = path.join(MARKETPLACES_DIR, mpName);
-        if (await fs.pathExists(mpDir))
-            continue;
-        // Look up the repo URL from default marketplaces
-        const defaultMp = defaultMarketplaces.find((m) => m.name === mpName);
-        if (!defaultMp?.source.repo)
-            continue;
-        try {
-            await addMarketplace(defaultMp.source.repo);
-            added.push(mpName);
-        }
-        catch (error) {
-            console.warn(`⚠ Failed to auto-add marketplace ${mpName}:`, error instanceof Error ? error.message : "Unknown error");
-        }
-    }
-    return added;
-}
+import { updatePlugin, isClaudeAvailable } from "../services/claude-cli.js";
+import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
 const CONTINUITY_PLUGIN_SENTINEL = "tmux-claude-continuity";
 const CONTINUITY_PLUGIN_SCRIPT = path.join(os.homedir(), ".tmux", "plugins", "tmux-claude-continuity", "scripts", "on_session_start.sh");
 /**
@@ -162,9 +80,13 @@ export async function prerunClaude(claudeArgs, options = {}) {
         }
         // STEP 0.5: Auto-add missing marketplaces
         // When plugins reference a marketplace that's not installed locally
-        // (e.g., settings synced from another machine), add it automatically.
+        // (e.g., settings synced from another machine or committed by a
+        // teammate in .claude/settings.json), add it automatically. Pass
+        // process.cwd() so project and local enabledPlugins are scanned —
+        // otherwise a freshly cloned repo whose only @magus references live
+        // in project settings looks "clean" from the global-scope view.
         if (await isClaudeAvailable()) {
-            const addedMarketplaces = await autoAddMissingMarketplaces();
+            const addedMarketplaces = await autoAddMissingMarketplaces(process.cwd());
             if (addedMarketplaces.length > 0) {
                 console.log(`✓ Auto-added marketplace(s): ${addedMarketplaces.join(", ")}`);
             }

package/src/prerunner/index.ts

@@ -11,9 +11,6 @@ import {
 	recoverMarketplaceSettings,
 	migrateMarketplaceRename,
 	cleanupExtraKnownMarketplaces,
-	getGlobalEnabledPlugins,
-	getEnabledPlugins,
-	getLocalEnabledPlugins,
 	readGlobalSettings,
 	writeGlobalSettings,
 	saveGlobalInstalledPluginVersion,
@@ -23,115 +20,13 @@ import {
 	checkPluginVersionMismatches,
 	formatMismatchWarning,
 } from "../services/plugin-version-check.js";
-import { parsePluginId } from "../utils/string-utils.js";
-import { defaultMarketplaces } from "../data/marketplaces.js";
-import {
-	updatePlugin,
-	addMarketplace,
-	isClaudeAvailable,
-} from "../services/claude-cli.js";
-
-const MARKETPLACES_DIR = path.join(
-	os.homedir(),
-	".claude",
-	"plugins",
-	"marketplaces",
-);
+import { updatePlugin, isClaudeAvailable } from "../services/claude-cli.js";
+import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
 
 export interface PrerunOptions {
 	force?: boolean; // Bypass cache and force update check
 }
 
-/**
- * Collect all unique marketplace names from enabled plugins across all settings scopes.
- * Returns a Set of marketplace names (e.g., "magus", "claude-plugins-official").
- */
-async function getReferencedMarketplaces(
-	projectPath?: string,
-): Promise<Set<string>> {
-	const marketplaceNames = new Set<string>();
-
-	// Collect plugin IDs from all scopes
-	const allPluginIds = new Set<string>();
-
-	try {
-		const global = await getGlobalEnabledPlugins();
-		for (const id of Object.keys(global)) allPluginIds.add(id);
-	} catch {
-		/* skip if unreadable */
-	}
-
-	if (projectPath) {
-		try {
-			const project = await getEnabledPlugins(projectPath);
-			for (const id of Object.keys(project)) allPluginIds.add(id);
-		} catch {
-			/* skip if unreadable */
-		}
-
-		try {
-			const local = await getLocalEnabledPlugins(projectPath);
-			for (const id of Object.keys(local)) allPluginIds.add(id);
-		} catch {
-			/* skip if unreadable */
-		}
-	}
-
-	// Parse marketplace names from plugin IDs
-	for (const pluginId of allPluginIds) {
-		const parsed = parsePluginId(pluginId);
-		if (parsed) {
-			marketplaceNames.add(parsed.marketplace);
-		}
-	}
-
-	return marketplaceNames;
-}
-
-/**
- * Check which referenced marketplaces are missing locally and auto-add them.
- * Only adds marketplaces with known repos (from defaultMarketplaces).
- *
- * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
- * Claude Code's `marketplace update` calls cacheMarketplaceFromGit() which
- * deletes the marketplace directory before re-cloning. If the clone fails
- * (network timeout, auth error), the directory stays permanently deleted
- * and ALL plugins from that marketplace break. See:
- * ai-docs/plugin-marketplace-bug-investigation.md
- *
- * Claude Code's own background autoupdate handles marketplace refreshing
- * after session start — claudeup should only recover genuinely missing
- * marketplaces, not trigger additional refresh cycles.
- */
-async function autoAddMissingMarketplaces(
-	projectPath?: string,
-): Promise<string[]> {
-	const referenced = await getReferencedMarketplaces(projectPath);
-	const added: string[] = [];
-
-	for (const mpName of referenced) {
-		// Check if marketplace directory exists locally
-		const mpDir = path.join(MARKETPLACES_DIR, mpName);
-		if (await fs.pathExists(mpDir)) continue;
-
-		// Look up the repo URL from default marketplaces
-		const defaultMp = defaultMarketplaces.find((m) => m.name === mpName);
-		if (!defaultMp?.source.repo) continue;
-
-		try {
-			await addMarketplace(defaultMp.source.repo);
-			added.push(mpName);
-		} catch (error) {
-			console.warn(
-				`⚠ Failed to auto-add marketplace ${mpName}:`,
-				error instanceof Error ? error.message : "Unknown error",
-			);
-		}
-	}
-
-	return added;
-}
-
 const CONTINUITY_PLUGIN_SENTINEL = "tmux-claude-continuity";
 const CONTINUITY_PLUGIN_SCRIPT = path.join(
 	os.homedir(),
@@ -228,9 +123,15 @@ export async function prerunClaude(
 
 		// STEP 0.5: Auto-add missing marketplaces
 		// When plugins reference a marketplace that's not installed locally
-		// (e.g., settings synced from another machine), add it automatically.
+		// (e.g., settings synced from another machine or committed by a
+		// teammate in .claude/settings.json), add it automatically. Pass
+		// process.cwd() so project and local enabledPlugins are scanned —
+		// otherwise a freshly cloned repo whose only @magus references live
+		// in project settings looks "clean" from the global-scope view.
 		if (await isClaudeAvailable()) {
-			const addedMarketplaces = await autoAddMissingMarketplaces();
+			const addedMarketplaces = await autoAddMissingMarketplaces(
+				process.cwd(),
+			);
 			if (addedMarketplaces.length > 0) {
 				console.log(
 					`✓ Auto-added marketplace(s): ${addedMarketplaces.join(", ")}`,

package/src/services/claude-cli.js

@@ -11,8 +11,9 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { which } from "../utils/command-utils.js";
-import { removeGlobalInstalledPluginVersion, removeLocalInstalledPluginVersion, } from "./claude-settings.js";
+import { isMarketplaceRegistered, removeGlobalInstalledPluginVersion, removeLocalInstalledPluginVersion, } from "./claude-settings.js";
 import { removeInstalledPluginVersion } from "./plugin-manager.js";
+import { defaultMarketplaces } from "../data/marketplaces.js";
 const execFileAsync = promisify(execFile);
 /**
  * Get the path to the claude CLI binary
@@ -48,13 +49,40 @@ async function execClaude(args, timeoutMs = 30000) {
         throw new Error(msg);
     }
 }
+/**
+ * Recover from a "not found in marketplace" error.
+ *
+ * Two distinct failure modes land in the same error string:
+ *   1. Marketplace is registered locally but stale (or uses the old
+ *      "directory" source) — fix the registry and refresh the clone.
+ *   2. Marketplace is not registered at all — look up its repo in
+ *      defaultMarketplaces and add it. This is the "new employee clones
+ *      a project whose .claude/settings.json enables @magus plugins but
+ *      magus was never registered on this machine" case.
+ *
+ * Returns true if recovery was attempted and a retry is worth trying.
+ */
+async function recoverMissingMarketplace(marketplace) {
+    if (await isMarketplaceRegistered(marketplace)) {
+        // Registered but stale — existing recovery path.
+        const { recoverMarketplaceSettings } = await import("./claude-settings.js");
+        await recoverMarketplaceSettings();
+        await updateMarketplace(marketplace);
+        return true;
+    }
+    const defaultMp = defaultMarketplaces.find((m) => m.name === marketplace);
+    if (!defaultMp?.source.repo)
+        return false;
+    await addMarketplace(defaultMp.source.repo);
+    return true;
+}
 /**
  * Install a plugin using claude CLI
  * Handles enabling + version tracking + cache copy in one shot.
  *
  * If the install fails because the plugin is "not found in marketplace",
- * recovers the marketplace registry (fixes stale "directory" sources),
- * triggers a marketplace update, and retries once.
+ * attempts to recover (add the marketplace if missing, or refresh it if
+ * stale) and retries once.
  */
 export async function installPlugin(pluginId, scope = "user") {
     try {
@@ -63,14 +91,8 @@ export async function installPlugin(pluginId, scope = "user") {
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("not found in marketplace")) {
-            const parts = pluginId.split("@");
-            const marketplace = parts[1];
-            if (marketplace) {
-                // Fix known_marketplaces.json first (stale "directory" → "github"),
-                // then update, then retry
-                const { recoverMarketplaceSettings } = await import("./claude-settings.js");
-                await recoverMarketplaceSettings();
-                await updateMarketplace(marketplace);
+            const marketplace = pluginId.split("@")[1];
+            if (marketplace && (await recoverMissingMarketplace(marketplace))) {
                 await execClaude([
                     "plugin",
                     "install",
@@ -135,12 +157,8 @@ export async function updatePlugin(pluginId, scope = "user") {
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         if (msg.includes("not found in marketplace")) {
-            const parts = pluginId.split("@");
-            const marketplace = parts[1];
-            if (marketplace) {
-                const { recoverMarketplaceSettings } = await import("./claude-settings.js");
-                await recoverMarketplaceSettings();
-                await updateMarketplace(marketplace);
+            const marketplace = pluginId.split("@")[1];
+            if (marketplace && (await recoverMissingMarketplace(marketplace))) {
                 await execClaude(["plugin", "install", pluginId, "--scope", scope], 60000);
                 return;
             }

package/src/services/claude-cli.ts

@@ -13,10 +13,12 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { which } from "../utils/command-utils.js";
 import {
+	isMarketplaceRegistered,
 	removeGlobalInstalledPluginVersion,
 	removeLocalInstalledPluginVersion,
 } from "./claude-settings.js";
 import { removeInstalledPluginVersion } from "./plugin-manager.js";
+import { defaultMarketplaces } from "../data/marketplaces.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -65,13 +67,46 @@ async function execClaude(args: string[], timeoutMs = 30000): Promise<string> {
 	}
 }
 
+/**
+ * Recover from a "not found in marketplace" error.
+ *
+ * Two distinct failure modes land in the same error string:
+ *   1. Marketplace is registered locally but stale (or uses the old
+ *      "directory" source) — fix the registry and refresh the clone.
+ *   2. Marketplace is not registered at all — look up its repo in
+ *      defaultMarketplaces and add it. This is the "new employee clones
+ *      a project whose .claude/settings.json enables @magus plugins but
+ *      magus was never registered on this machine" case.
+ *
+ * Returns true if recovery was attempted and a retry is worth trying.
+ */
+async function recoverMissingMarketplace(
+	marketplace: string,
+): Promise<boolean> {
+	if (await isMarketplaceRegistered(marketplace)) {
+		// Registered but stale — existing recovery path.
+		const { recoverMarketplaceSettings } = await import(
+			"./claude-settings.js"
+		);
+		await recoverMarketplaceSettings();
+		await updateMarketplace(marketplace);
+		return true;
+	}
+
+	const defaultMp = defaultMarketplaces.find((m) => m.name === marketplace);
+	if (!defaultMp?.source.repo) return false;
+
+	await addMarketplace(defaultMp.source.repo);
+	return true;
+}
+
 /**
  * Install a plugin using claude CLI
  * Handles enabling + version tracking + cache copy in one shot.
  *
  * If the install fails because the plugin is "not found in marketplace",
- * recovers the marketplace registry (fixes stale "directory" sources),
- * triggers a marketplace update, and retries once.
+ * attempts to recover (add the marketplace if missing, or refresh it if
+ * stale) and retries once.
  */
 export async function installPlugin(
 	pluginId: string,
@@ -83,16 +118,8 @@ export async function installPlugin(
 		const msg =
 			error instanceof Error ? error.message : String(error);
 		if (msg.includes("not found in marketplace")) {
-			const parts = pluginId.split("@");
-			const marketplace = parts[1];
-			if (marketplace) {
-				// Fix known_marketplaces.json first (stale "directory" → "github"),
-				// then update, then retry
-				const { recoverMarketplaceSettings } = await import(
-					"./claude-settings.js"
-				);
-				await recoverMarketplaceSettings();
-				await updateMarketplace(marketplace);
+			const marketplace = pluginId.split("@")[1];
+			if (marketplace && (await recoverMissingMarketplace(marketplace))) {
 				await execClaude([
 					"plugin",
 					"install",
@@ -174,14 +201,8 @@ export async function updatePlugin(
 		const msg =
 			error instanceof Error ? error.message : String(error);
 		if (msg.includes("not found in marketplace")) {
-			const parts = pluginId.split("@");
-			const marketplace = parts[1];
-			if (marketplace) {
-				const { recoverMarketplaceSettings } = await import(
-					"./claude-settings.js"
-				);
-				await recoverMarketplaceSettings();
-				await updateMarketplace(marketplace);
+			const marketplace = pluginId.split("@")[1];
+			if (marketplace && (await recoverMissingMarketplace(marketplace))) {
 				await execClaude(
 					["plugin", "install", pluginId, "--scope", scope],
 					60000,

package/src/services/claude-settings.js

@@ -1014,6 +1014,20 @@ async function readKnownMarketplaces() {
     }
     return {};
 }
+/**
+ * Check whether a marketplace is registered locally. A marketplace is
+ * considered registered when it has an entry in known_marketplaces.json
+ * AND its clone directory exists on disk. Either condition alone is not
+ * enough: an entry with a missing directory means the clone was lost; a
+ * directory without an entry means Claude Code doesn't know about it.
+ */
+export async function isMarketplaceRegistered(name) {
+    const known = await readKnownMarketplaces();
+    if (!known[name])
+        return false;
+    const marketplacesDir = path.join(os.homedir(), ".claude", "plugins", "marketplaces");
+    return fs.pathExists(path.join(marketplacesDir, name));
+}
 /**
  * Get the source path for a plugin from its marketplace
  * For directory-based marketplaces, returns the local directory path

package/src/services/claude-settings.ts

@@ -1325,6 +1325,27 @@ async function readKnownMarketplaces(): Promise<KnownMarketplaces> {
 	return {};
 }
 
+/**
+ * Check whether a marketplace is registered locally. A marketplace is
+ * considered registered when it has an entry in known_marketplaces.json
+ * AND its clone directory exists on disk. Either condition alone is not
+ * enough: an entry with a missing directory means the clone was lost; a
+ * directory without an entry means Claude Code doesn't know about it.
+ */
+export async function isMarketplaceRegistered(
+	name: string,
+): Promise<boolean> {
+	const known = await readKnownMarketplaces();
+	if (!known[name]) return false;
+	const marketplacesDir = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"marketplaces",
+	);
+	return fs.pathExists(path.join(marketplacesDir, name));
+}
+
 /**
  * Get the source path for a plugin from its marketplace
  * For directory-based marketplaces, returns the local directory path

package/src/services/marketplace-sync.js

@@ -0,0 +1,94 @@
+/**
+ * Marketplace sync service
+ *
+ * Auto-registers marketplaces that are referenced by `enabledPlugins`
+ * in any settings scope (global, project, local) but are not installed
+ * locally. Fixes the "new employee clones repo with committed .claude/
+ * settings but has never run `claude plugin marketplace add`" scenario.
+ *
+ * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
+ * Claude Code's `marketplace update` calls cacheMarketplaceFromGit()
+ * which deletes the marketplace directory before re-cloning. If the
+ * clone fails (network, auth, timeout), the directory stays permanently
+ * deleted. See ai-docs/plugin-marketplace-bug-investigation.md.
+ */
+import fs from "fs-extra";
+import path from "node:path";
+import os from "node:os";
+import { getGlobalEnabledPlugins, getEnabledPlugins, getLocalEnabledPlugins, isMarketplaceRegistered, } from "./claude-settings.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import { defaultMarketplaces } from "../data/marketplaces.js";
+import { addMarketplace } from "./claude-cli.js";
+const MARKETPLACES_DIR = path.join(os.homedir(), ".claude", "plugins", "marketplaces");
+/**
+ * Collect unique marketplace names from enabled plugins across all settings
+ * scopes. When `projectPath` is provided, project and local scopes are
+ * included; otherwise only the global scope is scanned.
+ */
+export async function getReferencedMarketplaces(projectPath) {
+    const marketplaceNames = new Set();
+    const allPluginIds = new Set();
+    try {
+        const global = await getGlobalEnabledPlugins();
+        for (const id of Object.keys(global))
+            allPluginIds.add(id);
+    }
+    catch {
+        /* skip if unreadable */
+    }
+    if (projectPath) {
+        try {
+            const project = await getEnabledPlugins(projectPath);
+            for (const id of Object.keys(project))
+                allPluginIds.add(id);
+        }
+        catch {
+            /* skip if unreadable */
+        }
+        try {
+            const local = await getLocalEnabledPlugins(projectPath);
+            for (const id of Object.keys(local))
+                allPluginIds.add(id);
+        }
+        catch {
+            /* skip if unreadable */
+        }
+    }
+    for (const pluginId of allPluginIds) {
+        const parsed = parsePluginId(pluginId);
+        if (parsed)
+            marketplaceNames.add(parsed.marketplace);
+    }
+    return marketplaceNames;
+}
+/** Re-exported for convenience — canonical implementation lives in claude-settings. */
+export { isMarketplaceRegistered };
+/**
+ * Register any referenced marketplaces that are missing locally.
+ * Looks up the GitHub repo in `defaultMarketplaces` and calls
+ * `claude plugin marketplace add` for each. Always writes to the global
+ * registry (`~/.claude/plugins/known_marketplaces.json`) — scope only
+ * controls which settings are scanned to build the reference list.
+ *
+ * Returns the names of marketplaces that were successfully added.
+ */
+export async function autoAddMissingMarketplaces(projectPath) {
+    const referenced = await getReferencedMarketplaces(projectPath);
+    const added = [];
+    for (const mpName of referenced) {
+        const mpDir = path.join(MARKETPLACES_DIR, mpName);
+        if (await fs.pathExists(mpDir))
+            continue;
+        const defaultMp = defaultMarketplaces.find((m) => m.name === mpName);
+        if (!defaultMp?.source.repo)
+            continue;
+        try {
+            await addMarketplace(defaultMp.source.repo);
+            added.push(mpName);
+        }
+        catch (error) {
+            console.warn(`⚠ Failed to auto-add marketplace ${mpName}:`, error instanceof Error ? error.message : "Unknown error");
+        }
+    }
+    return added;
+}

package/src/services/marketplace-sync.ts

@@ -0,0 +1,114 @@
+/**
+ * Marketplace sync service
+ *
+ * Auto-registers marketplaces that are referenced by `enabledPlugins`
+ * in any settings scope (global, project, local) but are not installed
+ * locally. Fixes the "new employee clones repo with committed .claude/
+ * settings but has never run `claude plugin marketplace add`" scenario.
+ *
+ * IMPORTANT: Only uses `marketplace add` (never `marketplace update`).
+ * Claude Code's `marketplace update` calls cacheMarketplaceFromGit()
+ * which deletes the marketplace directory before re-cloning. If the
+ * clone fails (network, auth, timeout), the directory stays permanently
+ * deleted. See ai-docs/plugin-marketplace-bug-investigation.md.
+ */
+import fs from "fs-extra";
+import path from "node:path";
+import os from "node:os";
+import {
+	getGlobalEnabledPlugins,
+	getEnabledPlugins,
+	getLocalEnabledPlugins,
+	isMarketplaceRegistered,
+} from "./claude-settings.js";
+import { parsePluginId } from "../utils/string-utils.js";
+import { defaultMarketplaces } from "../data/marketplaces.js";
+import { addMarketplace } from "./claude-cli.js";
+
+const MARKETPLACES_DIR = path.join(
+	os.homedir(),
+	".claude",
+	"plugins",
+	"marketplaces",
+);
+
+/**
+ * Collect unique marketplace names from enabled plugins across all settings
+ * scopes. When `projectPath` is provided, project and local scopes are
+ * included; otherwise only the global scope is scanned.
+ */
+export async function getReferencedMarketplaces(
+	projectPath?: string,
+): Promise<Set<string>> {
+	const marketplaceNames = new Set<string>();
+	const allPluginIds = new Set<string>();
+
+	try {
+		const global = await getGlobalEnabledPlugins();
+		for (const id of Object.keys(global)) allPluginIds.add(id);
+	} catch {
+		/* skip if unreadable */
+	}
+
+	if (projectPath) {
+		try {
+			const project = await getEnabledPlugins(projectPath);
+			for (const id of Object.keys(project)) allPluginIds.add(id);
+		} catch {
+			/* skip if unreadable */
+		}
+
+		try {
+			const local = await getLocalEnabledPlugins(projectPath);
+			for (const id of Object.keys(local)) allPluginIds.add(id);
+		} catch {
+			/* skip if unreadable */
+		}
+	}
+
+	for (const pluginId of allPluginIds) {
+		const parsed = parsePluginId(pluginId);
+		if (parsed) marketplaceNames.add(parsed.marketplace);
+	}
+
+	return marketplaceNames;
+}
+
+/** Re-exported for convenience — canonical implementation lives in claude-settings. */
+export { isMarketplaceRegistered };
+
+/**
+ * Register any referenced marketplaces that are missing locally.
+ * Looks up the GitHub repo in `defaultMarketplaces` and calls
+ * `claude plugin marketplace add` for each. Always writes to the global
+ * registry (`~/.claude/plugins/known_marketplaces.json`) — scope only
+ * controls which settings are scanned to build the reference list.
+ *
+ * Returns the names of marketplaces that were successfully added.
+ */
+export async function autoAddMissingMarketplaces(
+	projectPath?: string,
+): Promise<string[]> {
+	const referenced = await getReferencedMarketplaces(projectPath);
+	const added: string[] = [];
+
+	for (const mpName of referenced) {
+		const mpDir = path.join(MARKETPLACES_DIR, mpName);
+		if (await fs.pathExists(mpDir)) continue;
+
+		const defaultMp = defaultMarketplaces.find((m) => m.name === mpName);
+		if (!defaultMp?.source.repo) continue;
+
+		try {
+			await addMarketplace(defaultMp.source.repo);
+			added.push(mpName);
+		} catch (error) {
+			console.warn(
+				`⚠ Failed to auto-add marketplace ${mpName}:`,
+				error instanceof Error ? error.message : "Unknown error",
+			);
+		}
+	}
+
+	return added;
+}

package/src/ui/App.js

@@ -8,6 +8,8 @@ import { ModalContainer } from "./components/modals/index.js";
 import { PluginsScreen, McpScreen, McpRegistryScreen, SettingsScreen, CliToolsScreen, ModelSelectorScreen, ProfilesScreen, SkillsScreen, } from "./screens/index.js";
 import { repairAllMarketplaces } from "../services/local-marketplace.js";
 import { migrateMarketplaceRename, recoverMarketplaceSettings, } from "../services/claude-settings.js";
+import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
+import { isClaudeAvailable } from "../services/claude-cli.js";
 import { checkPluginVersionMismatches, } from "../services/plugin-version-check.js";
 import { useMismatchModal } from "./hooks/useMismatchModal.js";
 import { checkForUpdates, getCurrentVersion, } from "../services/version-check.js";
@@ -222,6 +224,23 @@ function AppContent({ onExit }) {
         });
         // Migrate old marketplace names -> magus (idempotent), then repair plugin.json files
         migrateMarketplaceRename().catch(() => { }); // non-blocking, best-effort
+        // Auto-add marketplaces referenced by enabledPlugins but missing from
+        // the local registry. Fixes the "fresh clone of a project whose
+        // .claude/settings.json enables @magus plugins but this machine has
+        // never run `claude plugin marketplace add`" case.
+        (async () => {
+            try {
+                if (!(await isClaudeAvailable()))
+                    return;
+                const added = await autoAddMissingMarketplaces(process.cwd());
+                if (added.length > 0) {
+                    setRecoveryReport(`added marketplace(s): ${added.join(", ")}`);
+                }
+            }
+            catch {
+                // non-fatal: user can still install marketplaces manually
+            }
+        })();
         // Recover stale marketplace registry entries (e.g. "directory" -> "github")
         recoverMarketplaceSettings()
             .then(async (recovery) => {

package/src/ui/App.tsx

@@ -28,6 +28,8 @@ import {
 	migrateMarketplaceRename,
 	recoverMarketplaceSettings,
 } from "../services/claude-settings.js";
+import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
+import { isClaudeAvailable } from "../services/claude-cli.js";
 import {
 	checkPluginVersionMismatches,
 	type VersionMismatchInfo,
@@ -352,6 +354,22 @@ function AppContent({ onExit }: AppContentProps) {
 		// Migrate old marketplace names -> magus (idempotent), then repair plugin.json files
 		migrateMarketplaceRename().catch(() => {}); // non-blocking, best-effort
 
+		// Auto-add marketplaces referenced by enabledPlugins but missing from
+		// the local registry. Fixes the "fresh clone of a project whose
+		// .claude/settings.json enables @magus plugins but this machine has
+		// never run `claude plugin marketplace add`" case.
+		(async () => {
+			try {
+				if (!(await isClaudeAvailable())) return;
+				const added = await autoAddMissingMarketplaces(process.cwd());
+				if (added.length > 0) {
+					setRecoveryReport(`added marketplace(s): ${added.join(", ")}`);
+				}
+			} catch {
+				// non-fatal: user can still install marketplaces manually
+			}
+		})();
+
 		// Recover stale marketplace registry entries (e.g. "directory" -> "github")
 		recoverMarketplaceSettings()
 			.then(async (recovery) => {

package/src/ui/components/modals/VersionMismatchModal.js

@@ -26,7 +26,7 @@ export function VersionMismatchModal({ mismatches, defaultIndex, }) {
     // Column widths chosen to fit a 64-wide modal with padding
     const NAME_W = 22;
     const VER_W = 12;
-    return (_jsxs("box", { flexDirection: "column", border: true, borderStyle: "rounded", borderColor: COLOR_BORDER, backgroundColor: COLOR_BG, paddingLeft: 3, paddingRight: 3, paddingTop: 1, paddingBottom: 1, width: 64, children: [_jsxs("box", { marginBottom: 1, children: [_jsx("text", { fg: COLOR_WARN, children: "\u26A0 " }), _jsx("text", { fg: COLOR_TITLE, children: _jsx("strong", { children: "Plugin Version Mismatch" }) })] }), _jsxs("box", { flexDirection: "column", marginBottom: 1, children: [_jsxs("text", { fg: COLOR_MUTED, children: ["Plugins in this project will load ", _jsx("strong", { children: "wrong versions" })] }), _jsx("text", { fg: COLOR_MUTED, children: "due to a Claude Code bug (#45997)." })] }), _jsxs("box", { flexDirection: "column", marginBottom: 1, children: [_jsx("text", { fg: COLOR_DIM, children: _jsxs("strong", { children: ["Plugin".padEnd(NAME_W), "Loaded".padEnd(VER_W), "Expected".padEnd(VER_W)] }) }), _jsxs("text", { fg: COLOR_BORDER, children: ["─".repeat(NAME_W - 1), " ", "─".repeat(VER_W - 1), " ", "─".repeat(VER_W - 1)] }), mismatches.map((m) => {
+    return (_jsxs("box", { flexDirection: "column", border: true, borderStyle: "rounded", borderColor: COLOR_BORDER, backgroundColor: COLOR_BG, paddingLeft: 3, paddingRight: 3, paddingTop: 1, paddingBottom: 1, width: 64, children: [_jsx("box", { marginBottom: 1, children: _jsxs("text", { fg: COLOR_TITLE, children: [_jsx("span", { fg: COLOR_WARN, children: "\u26A0 " }), _jsx("strong", { children: "Plugin Version Mismatch" })] }) }), _jsxs("box", { flexDirection: "column", marginBottom: 1, children: [_jsxs("text", { fg: COLOR_MUTED, children: ["Plugins in this project will load ", _jsx("strong", { children: "wrong versions" })] }), _jsx("text", { fg: COLOR_MUTED, children: "due to a Claude Code bug (#45997)." })] }), _jsxs("box", { flexDirection: "column", marginBottom: 1, children: [_jsx("text", { fg: COLOR_DIM, children: _jsxs("strong", { children: ["Plugin".padEnd(NAME_W), "Loaded".padEnd(VER_W), "Expected".padEnd(VER_W)] }) }), _jsxs("text", { fg: COLOR_BORDER, children: ["─".repeat(NAME_W - 1), " ", "─".repeat(VER_W - 1), " ", "─".repeat(VER_W - 1)] }), mismatches.map((m) => {
                         const name = shortName(m.pluginId, NAME_W - 1);
                         const loaded = `v${shortVersion(m.firstEntryVersion, VER_W - 2)}`;
                         const expected = `v${shortVersion(m.currentProjectVersion, VER_W - 2)}`;

package/src/ui/components/modals/VersionMismatchModal.tsx

@@ -56,8 +56,8 @@ export function VersionMismatchModal({
 		>
 			{/* Title */}
 			<box marginBottom={1}>
-				<text fg={COLOR_WARN}>⚠ </text>
 				<text fg={COLOR_TITLE}>
+					<span fg={COLOR_WARN}>⚠ </span>
 					<strong>Plugin Version Mismatch</strong>
 				</text>
 			</box>

package/src/ui/screens/PluginsScreen.js

@@ -14,7 +14,7 @@ import { saveProfile } from "../../services/profiles.js";
 import { installPlugin as cliInstallPlugin, uninstallPlugin as cliUninstallPlugin, updatePlugin as cliUpdatePlugin, } from "../../services/claude-cli.js";
 import { getPluginEnvRequirements, getPluginSourcePath, } from "../../services/plugin-mcp-config.js";
 import { getPluginSetupFromSource, checkMissingDeps, installPluginDeps, } from "../../services/plugin-setup.js";
-import { checkSinglePluginMismatch, } from "../../services/plugin-version-check.js";
+import { checkPluginVersionMismatches, checkSinglePluginMismatch, } from "../../services/plugin-version-check.js";
 import { useMismatchModal } from "../hooks/useMismatchModal.js";
 import { buildPluginBrowserItems, } from "../adapters/pluginsAdapter.js";
 import { renderPluginRow, renderPluginDetail, } from "../renderers/pluginRenderers.js";
@@ -215,6 +215,8 @@ export function PluginsScreen() {
             handleUpdate();
         else if (event.name === "a")
             handleUpdateAll();
+        else if (event.name === "m")
+            handleCheckMismatches();
         else if (event.name === "s")
             handleSaveAsProfile();
     });
@@ -589,6 +591,25 @@ export function PluginsScreen() {
             await modal.message("Error", `Failed to update: ${error}`, "error");
         }
     };
+    /**
+     * Manual on-demand check for plugin version mismatches across projects.
+     * Bound to the `m` keybind. Shows a success message if everything is
+     * aligned, or the interactive fix modal if any mismatches are found.
+     */
+    const handleCheckMismatches = async () => {
+        try {
+            const projectPath = state.projectPath || process.cwd();
+            const mismatches = await checkPluginVersionMismatches(projectPath);
+            if (mismatches.length === 0) {
+                await modal.message("No Mismatches", "All enabled plugins in this project will load their expected versions. No action needed.", "success");
+                return;
+            }
+            mismatchModal.show(mismatches);
+        }
+        catch (error) {
+            await modal.message("Error", `Failed to check mismatches: ${error}`, "error");
+        }
+    };
     const handleScopeToggle = async (scope) => {
         const item = selectableItems[pluginsState.selectedIndex];
         if (!item || item.kind !== "plugin")
@@ -715,7 +736,7 @@ export function PluginsScreen() {
     const selectedItem = selectableItems[pluginsState.selectedIndex];
     const footerHints = isSearchActive
         ? "type to filter │ Enter:done │ Esc:clear"
-        : "u/p/l:toggle │ U:update │ a:all │ s:profile │ /:search";
+        : "u/p/l:toggle │ U:update │ a:all │ m:mismatches │ s:profile │ /:search";
     const scopeLabel = pluginsState.scope === "global" ? "Global" : "Project";
     const plugins = pluginsState.plugins.status === "success" ? pluginsState.plugins.data : [];
     const installedCount = plugins.filter((p) => p.enabled).length;

package/src/ui/screens/PluginsScreen.tsx

@@ -39,6 +39,7 @@ import {
 	installPluginDeps,
 } from "../../services/plugin-setup.js";
 import {
+	checkPluginVersionMismatches,
 	checkSinglePluginMismatch,
 	type VersionMismatchInfo,
 } from "../../services/plugin-version-check.js";
@@ -266,6 +267,7 @@ export function PluginsScreen() {
 		else if (event.name === "d") handleRemoveDeprecated();
 		else if (event.name === "U") handleUpdate();
 		else if (event.name === "a") handleUpdateAll();
+		else if (event.name === "m") handleCheckMismatches();
 		else if (event.name === "s") handleSaveAsProfile();
 	});
 
@@ -741,6 +743,33 @@ export function PluginsScreen() {
 		}
 	};
 
+	/**
+	 * Manual on-demand check for plugin version mismatches across projects.
+	 * Bound to the `m` keybind. Shows a success message if everything is
+	 * aligned, or the interactive fix modal if any mismatches are found.
+	 */
+	const handleCheckMismatches = async () => {
+		try {
+			const projectPath = state.projectPath || process.cwd();
+			const mismatches = await checkPluginVersionMismatches(projectPath);
+			if (mismatches.length === 0) {
+				await modal.message(
+					"No Mismatches",
+					"All enabled plugins in this project will load their expected versions. No action needed.",
+					"success",
+				);
+				return;
+			}
+			mismatchModal.show(mismatches);
+		} catch (error) {
+			await modal.message(
+				"Error",
+				`Failed to check mismatches: ${error}`,
+				"error",
+			);
+		}
+	};
+
 	const handleScopeToggle = async (scope: "user" | "project" | "local") => {
 		const item = selectableItems[pluginsState.selectedIndex];
 		if (!item || item.kind !== "plugin") return;
@@ -909,7 +938,7 @@ export function PluginsScreen() {
 
 	const footerHints = isSearchActive
 		? "type to filter │ Enter:done │ Esc:clear"
-		: "u/p/l:toggle │ U:update │ a:all │ s:profile │ /:search";
+		: "u/p/l:toggle │ U:update │ a:all │ m:mismatches │ s:profile │ /:search";
 
 	const scopeLabel = pluginsState.scope === "global" ? "Global" : "Project";
 	const plugins: PluginInfo[] =