claudeup 4.13.0 → 4.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "4.13.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) => {