@geminilight/mindos 0.5.6 → 0.5.8

package/README.md

@@ -48,21 +48,23 @@ MindOS is a **Human-AI Collaborative Mind System**—a local-first knowledge bas
 > Help me execute the XXX SOP from MindOS.
 > ```
 
-## 🧠 Core Value: Human-AI Shared Mind
+## 🧠 Human-AI Shared Mind
 
-**1. Global Sync — Break Memory Silos**
+> No more fragmented memory, no more black-box behavior, no more lost experience.
 
-Traditional notes are scattered across tools and APIs, so agents miss your real context when it matters. MindOS turns your local knowledge into one MCP-ready source, so every agent can sync your Profile, SOPs, and live working memory.
+**1. Global Sync — Breaking Memory Silos**
 
-**2. Transparent and Controllable — Eliminate Memory Black Boxes**
+Each Agent keeps its own memory — switching tools means manually hauling context. **MindOS lets all Agents share one knowledge base via MCP and Skills — record once, reuse everywhere.**
 
-Most assistant memory lives in black boxes, leaving humans unable to inspect or correct how decisions are made. MindOS writes retrieval and execution traces into local plain text, so you can audit, intervene, and improve continuously.
+**2. Transparent & Controllable — No More Black Boxes**
+
+What did your Agent remember? Is it even correct? You have no way to know. **MindOS saves every read/write as local plain text — humans can audit, correct, and delete in the GUI.**
 
 **3. Symbiotic Evolution — Experience Flows Back as Instructions**
 
-Static documents are hard to synchronize and weak as execution systems in real human-agent collaboration. MindOS makes notes agent-ready and reference-linked, so daily writing naturally becomes executable workflows that evolve with you.
+All that experience from your conversations — gone the moment you close the window. **MindOS auto-distills conversation experience into Skills/SOPs. Notes are instructions. The knowledge base gets better with use.**
 
-> **Foundation:** Local-first by default - all data stays in local plain text for privacy, ownership, and speed.
+> **Foundation:** Local-first by default — all data stays in local plain text for privacy, ownership, and speed.
 
 ## ✨ Features
 
@@ -80,7 +82,7 @@ Static documents are hard to synchronize and weak as execution systems in real h
 
 **Infrastructure**
 
-- **Reference Sync**: keep cross-file status and context aligned via links/backlinks.
+- **Security**: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes.
 - **Knowledge Graph**: visualize relationships and dependencies across notes.
 - **Git Time Machine**: track every edit, audit history, and roll back safely.
 - **Cross-Device Sync**: auto-commit, push, and pull via Git — edits on one device appear on all others within minutes.

package/README_zh.md

@@ -48,19 +48,21 @@ MindOS 是一个**人机协同心智系统**——基于本地优先的协作知
 > 帮我执行 MindOS 里的 XXX 工作流。
 > ```
 
-## 🧠 核心价值：人机共享心智
+## 🧠 人机共享心智
+
+> 记忆不再割裂，行为不再黑箱，经验不再断流。
 
 **1. 全局同步 — 打破记忆割裂**
 
-传统笔记分散在不同工具和接口中，Agent 在关键时刻拿不到你的真实上下文。MindOS 把本地知识统一为 MCP 可读的单一来源，让所有 Agent 同步你的 Profile、SOP 与实时记忆。
+多个 Agent 各记各的，切换工具靠人工搬运上下文。**MindOS 通过 MCP 和 Skill 让所有 Agent 共享同一份知识库——一处记录，全局复用。**
 
 **2. 透明可控 — 消除记忆黑箱**
 
-多数助手记忆封闭在黑箱里，人类难以审查和纠正决策过程。MindOS 将检索与执行轨迹沉淀为本地纯文本，让你可以持续审计、干预与优化。
+Agent 记了什么、记对没有，用户无从知晓。**MindOS 将每次读写沉淀为本地纯文本，人类可在 GUI 中审查、修正、删除。**
 
 **3. 共生演进 — 经验回流为指令**
 
-静态文档难同步，也难在真实人机协作中承担执行系统角色。MindOS 让笔记天然成为 Agent 可执行的指令，通过引用链接组织知识，日常记录自然变成可执行工作流并持续进化。
+对话里攒下的经验，关掉窗口就散了。**MindOS 自动将对话经验沉淀为 Skill/SOP，笔记即指令，知识库越用越好。**
 
 > **底层原则：** 默认本地优先，全部数据以本地纯文本保存，兼顾隐私、主权与性能。
 
@@ -80,7 +82,7 @@ MindOS 是一个**人机协同心智系统**——基于本地优先的协作知
 
 **基础设施**
 
-- **引用同步**：通过引用与反向链接保持跨文件状态一致。
+- **安全防线**：Bearer Token 认证、路径沙箱、INSTRUCTION.md 写保护、原子写入。
 - **知识图谱**：可视化笔记间关系与依赖。
 - **Git 时光机**：记录修改历史，支持审计与安全回滚。
 - **跨设备同步**：通过 Git 自动 commit、push、pull —— 一台设备的编辑几分钟内同步到所有设备。

package/app/app/api/mcp/agents/route.ts

@@ -1,14 +1,16 @@
 export const dynamic = 'force-dynamic';
 import { NextResponse } from 'next/server';
-import { MCP_AGENTS, detectInstalled } from '@/lib/mcp-agents';
+import { MCP_AGENTS, detectInstalled, detectAgentPresence } from '@/lib/mcp-agents';
 
 export async function GET() {
   try {
     const agents = Object.entries(MCP_AGENTS).map(([key, agent]) => {
       const status = detectInstalled(key);
+      const present = detectAgentPresence(key);
       return {
         key,
         name: agent.name,
+        present,
         installed: status.installed,
         scope: status.scope,
         transport: status.transport,

package/app/app/api/mcp/install-skill/route.ts

@@ -15,7 +15,7 @@ const UNIVERSAL_AGENTS = new Set([
 ]);
 
 // Agents that do NOT support Skills at all
-const SKILL_UNSUPPORTED = new Set(['claude-desktop']);
+const SKILL_UNSUPPORTED = new Set<string>([]);
 
 // MCP agent key → npx skills agent name (for non-universal agents)
 const AGENT_NAME_MAP: Record<string, string> = {

package/app/app/api/restart/route.ts

@@ -7,14 +7,38 @@ export async function POST() {
   try {
     // process.cwd() is the Next.js app directory; cli.js is one level up at project root/bin/
     const cliPath = resolve(process.cwd(), '../bin/cli.js');
-    const child = spawn(process.execPath, [cliPath, 'start'], {
+    // Use 'restart' (stop all → wait for ports free → start) instead of bare
+    // 'start' which would fail assertPortFree because the current process and
+    // its MCP child are still holding the ports.
+    //
+    // IMPORTANT: Strip MINDOS_* env vars so the child's loadConfig() reads
+    // the *updated* config file instead of inheriting stale values from this
+    // process.  Without this, changing ports in the GUI has no effect on the
+    // restarted server — it would start on the old ports.
+    //
+    // Pass the current (old) ports via MINDOS_OLD_* so the restart command
+    // can clean up processes still listening on the previous ports.
+    const childEnv = { ...process.env };
+    const oldWebPort = childEnv.MINDOS_WEB_PORT;
+    const oldMcpPort = childEnv.MINDOS_MCP_PORT;
+    delete childEnv.MINDOS_WEB_PORT;
+    delete childEnv.MINDOS_MCP_PORT;
+    delete childEnv.MIND_ROOT;
+    delete childEnv.AUTH_TOKEN;
+    delete childEnv.WEB_PASSWORD;
+    if (oldWebPort) childEnv.MINDOS_OLD_WEB_PORT = oldWebPort;
+    if (oldMcpPort) childEnv.MINDOS_OLD_MCP_PORT = oldMcpPort;
+    const child = spawn(process.execPath, [cliPath, 'restart'], {
       detached: true,
       stdio: 'ignore',
-      env: process.env,
+      env: childEnv,
     });
     child.unref();
-    // Give a brief moment for the response to be sent before exiting
-    setTimeout(() => process.exit(0), 500);
+    // Give a brief moment for the response to be sent before exiting.
+    // The spawned 'restart' command will handle stopping this process via
+    // stopMindos() (kill by PID + port cleanup), so process.exit here is
+    // just a safety net in case the parent isn't killed cleanly.
+    setTimeout(() => process.exit(0), 1500);
     return NextResponse.json({ ok: true });
   } catch (err) {
     return NextResponse.json({ error: String(err) }, { status: 500 });

package/app/components/SetupWizard.tsx

@@ -36,6 +36,7 @@ interface PortStatus {
 interface AgentEntry {
   key: string;
   name: string;
+  present: boolean;
   installed: boolean;
   hasProjectScope: boolean;
   hasGlobalScope: boolean;
@@ -511,7 +512,7 @@ function Step5({
     return agentTransport;
   };
 
-  const getStatusBadge = (key: string, installed: boolean) => {
+  const getStatusBadge = (key: string, agent: AgentEntry) => {
     const st = agentStatuses[key];
     if (st) {
       if (st.state === 'installing') return (
@@ -533,16 +534,22 @@ function Step5({
         </span>
       );
     }
-    if (installed) return (
+    if (agent.installed) return (
       <span className="text-[11px] px-1.5 py-0.5 rounded"
         style={{ background: 'rgba(34,197,94,0.12)', color: '#22c55e' }}>
         {settingsMcp.installed}
       </span>
     );
+    if (agent.present) return (
+      <span className="text-[11px] px-1.5 py-0.5 rounded"
+        style={{ background: 'rgba(245,158,11,0.12)', color: '#f59e0b' }}>
+        {s.agentDetected ?? 'detected'}
+      </span>
+    );
     return (
       <span className="text-[11px] px-1.5 py-0.5 rounded"
         style={{ background: 'rgba(100,100,120,0.1)', color: 'var(--muted-foreground)' }}>
-        {s.agentNotInstalled}
+        {s.agentNotFound ?? s.agentNotInstalled}
       </span>
     );
   };
@@ -581,7 +588,7 @@ function Step5({
                   style={{ background: 'rgba(100,100,120,0.08)', color: 'var(--muted-foreground)' }}>
                   {getEffectiveTransport(agent)}
                 </span>
-                {getStatusBadge(agent.key, agent.installed)}
+                {getStatusBadge(agent.key, agent)}
               </label>
             ))}
           </div>
@@ -936,7 +943,7 @@ export default function SetupWizard() {
           if (data.agents) {
             setAgents(data.agents);
             setSelectedAgents(new Set(
-              (data.agents as AgentEntry[]).filter(a => a.installed).map(a => a.key)
+              (data.agents as AgentEntry[]).filter(a => a.installed || a.present).map(a => a.key)
             ));
           }
         })

package/app/components/settings/McpTab.tsx

@@ -22,6 +22,7 @@ interface McpStatus {
 interface AgentInfo {
   key: string;
   name: string;
+  present: boolean;
   installed: boolean;
   scope?: string;
   transport?: string;
@@ -231,7 +232,9 @@ function AgentInstall({ agents, t, onRefresh }: { agents: AgentInfo[]; t: any; o
                 <span className="text-[10px] text-muted-foreground">{agent.scope}</span>
               </>
             ) : (
-              <span className="text-[10px] text-muted-foreground">{m?.notInstalled ?? 'Not installed'}</span>
+              <span className="text-[10px] text-muted-foreground">
+                {agent.present ? (m?.detected ?? 'Detected') : (m?.notFound ?? 'Not found')}
+              </span>
             )}
             {/* Scope selector */}
             {selected.has(agent.key) && agent.hasProjectScope && agent.hasGlobalScope && (

package/app/lib/i18n.ts

@@ -197,6 +197,8 @@ export const messages = {
         global: 'Global',
         installed: 'Installed',
         notInstalled: 'Not installed',
+        detected: 'Detected',
+        notFound: 'Not found',
         transportStdio: 'stdio (recommended)',
         transportHttp: 'http',
         transportAuto: 'auto (recommended)',
@@ -325,6 +327,8 @@ export const messages = {
       agentNoneSelected: 'No agents selected — you can configure later in Settings → MCP.',
       agentSkipLater: 'Skip — configure later',
       agentNotInstalled: 'not installed',
+      agentDetected: 'detected',
+      agentNotFound: 'not found',
       agentStatusOk: 'configured',
       agentStatusError: 'failed',
       agentInstalling: 'Configuring…',
@@ -566,6 +570,8 @@ export const messages = {
         global: '全局',
         installed: '已安装',
         notInstalled: '未安装',
+        detected: '已检测',
+        notFound: '未找到',
         transportStdio: 'stdio（推荐）',
         transportHttp: 'http',
         transportAuto: '自动（推荐）',
@@ -694,6 +700,8 @@ export const messages = {
       agentNoneSelected: '未选择 agent — 可稍后在 设置 → MCP 中配置。',
       agentSkipLater: '跳过 — 稍后配置',
       agentNotInstalled: '未安装',
+      agentDetected: '已检测到',
+      agentNotFound: '未找到',
       agentStatusOk: '已配置',
       agentStatusError: '失败',
       agentInstalling: '配置中…',

package/app/lib/mcp-agents.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { execSync } from 'child_process';
 
 export function expandHome(p: string): string {
   return p.startsWith('~/') ? path.resolve(os.homedir(), p.slice(2)) : p;
@@ -12,20 +13,90 @@ export interface AgentDef {
   global: string;
   key: string;
   preferredTransport: 'stdio' | 'http';
+  /** CLI binary name for presence detection (e.g. 'claude'). Optional. */
+  presenceCli?: string;
+  /** Data directories for presence detection. Any one existing → present. */
+  presenceDirs?: string[];
 }
 
 export const MCP_AGENTS: Record<string, AgentDef> = {
-  'claude-code':    { name: 'Claude Code',    project: '.mcp.json',                       global: '~/.claude.json',    key: 'mcpServers', preferredTransport: 'stdio' },
-  'claude-desktop': { name: 'Claude Desktop', project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Claude/claude_desktop_config.json' : '~/.config/Claude/claude_desktop_config.json', key: 'mcpServers', preferredTransport: 'http' },
-  'cursor':         { name: 'Cursor',          project: '.cursor/mcp.json',                global: '~/.cursor/mcp.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'windsurf':       { name: 'Windsurf',        project: null,                               global: '~/.codeium/windsurf/mcp_config.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'cline':          { name: 'Cline',           project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json' : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'trae':           { name: 'Trae',            project: '.trae/mcp.json',                  global: '~/.trae/mcp.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'gemini-cli':     { name: 'Gemini CLI',      project: '.gemini/settings.json',           global: '~/.gemini/settings.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'openclaw':       { name: 'OpenClaw',        project: null,                               global: '~/.openclaw/mcp.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'codebuddy':      { name: 'CodeBuddy',       project: null,                               global: '~/.claude-internal/.claude.json', key: 'mcpServers', preferredTransport: 'stdio' },
+  'claude-code': {
+    name: 'Claude Code',
+    project: '.mcp.json',
+    global: '~/.claude.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'claude',
+    presenceDirs: ['~/.claude/'],
+  },
+  'cursor': {
+    name: 'Cursor',
+    project: '.cursor/mcp.json',
+    global: '~/.cursor/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.cursor/'],
+  },
+  'windsurf': {
+    name: 'Windsurf',
+    project: null,
+    global: '~/.codeium/windsurf/mcp_config.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.codeium/windsurf/'],
+  },
+  'cline': {
+    name: 'Cline',
+    project: null,
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
+      : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/',
+      '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/',
+    ],
+  },
+  'trae': {
+    name: 'Trae',
+    project: '.trae/mcp.json',
+    global: '~/.trae/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.trae/'],
+  },
+  'gemini-cli': {
+    name: 'Gemini CLI',
+    project: '.gemini/settings.json',
+    global: '~/.gemini/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'gemini',
+    presenceDirs: ['~/.gemini/'],
+  },
+  'openclaw': {
+    name: 'OpenClaw',
+    project: null,
+    global: '~/.openclaw/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'openclaw',
+    presenceDirs: ['~/.openclaw/'],
+  },
+  'codebuddy': {
+    name: 'CodeBuddy',
+    project: null,
+    global: '~/.claude-internal/.claude.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'claude-internal',
+    presenceDirs: ['~/.claude-internal/'],
+  },
 };
 
+/* ── MindOS MCP Install Detection ──────────────────────────────────────── */
+
 export function detectInstalled(agentKey: string): { installed: boolean; scope?: string; transport?: string; configPath?: string } {
   const agent = MCP_AGENTS[agentKey];
   if (!agent) return { installed: false };
@@ -47,3 +118,23 @@ export function detectInstalled(agentKey: string): { installed: boolean; scope?:
 
   return { installed: false };
 }
+
+/* ── Agent Presence Detection ──────────────────────────────────────────── */
+
+export function detectAgentPresence(agentKey: string): boolean {
+  const agent = MCP_AGENTS[agentKey];
+  if (!agent) return false;
+  // 1. CLI check
+  if (agent.presenceCli) {
+    try {
+      execSync(
+        process.platform === 'win32' ? `where ${agent.presenceCli}` : `which ${agent.presenceCli}`,
+        { stdio: 'pipe' },
+      );
+      return true;
+    } catch { /* not found */ }
+  }
+  // 2. Dir check
+  if (agent.presenceDirs?.some(d => fs.existsSync(expandHome(d)))) return true;
+  return false;
+}

package/app/proxy.ts

@@ -16,8 +16,9 @@ export async function proxy(req: NextRequest) {
 
   // --- API protection (AUTH_TOKEN) ---
   if (pathname.startsWith('/api/')) {
-    // /api/auth handles its own password validation — never block it
-    if (pathname === '/api/auth') return NextResponse.next();
+    // /api/auth handles its own password validation — never block it.
+    // /api/health is unauthenticated so check-port can detect this MindOS instance.
+    if (pathname === '/api/auth' || pathname === '/api/health') return NextResponse.next();
 
     if (!authToken) return NextResponse.next();
 

package/bin/cli.js

@@ -317,16 +317,39 @@ const commands = {
   stop: () => stopMindos(),
 
   restart: async () => {
+    // Capture old ports BEFORE loadConfig overwrites env vars, so we can
+    // clean up processes that are still listening on the previous ports
+    // (e.g. user changed ports in the GUI and config was already saved).
+    // Sources: (1) MINDOS_OLD_* set by /api/restart when it strips the
+    //              current env, (2) current MINDOS_*_PORT env vars.
+    const oldWebPort = process.env.MINDOS_OLD_WEB_PORT || process.env.MINDOS_WEB_PORT;
+    const oldMcpPort = process.env.MINDOS_OLD_MCP_PORT || process.env.MINDOS_MCP_PORT;
+
     loadConfig();
-    const webPort = Number(process.env.MINDOS_WEB_PORT || '3000');
-    const mcpPort = Number(process.env.MINDOS_MCP_PORT || '8787');
-    stopMindos();
-    // Wait until both ports are actually free (up to 15s)
+
+    // After loadConfig, env vars reflect the NEW config (or old if unchanged).
+    const newWebPort = Number(process.env.MINDOS_WEB_PORT || '3000');
+    const newMcpPort = Number(process.env.MINDOS_MCP_PORT || '8787');
+
+    // Collect old ports that differ from new ones — processes may still be
+    // listening there even though config already points to the new ports.
+    const extraPorts = [];
+    if (oldWebPort && Number(oldWebPort) !== newWebPort) extraPorts.push(oldWebPort);
+    if (oldMcpPort && Number(oldMcpPort) !== newMcpPort) extraPorts.push(oldMcpPort);
+
+    stopMindos({ extraPorts });
+
+    // Wait until ALL ports (old + new) are actually free (up to 15s)
+    const allPorts = new Set([newWebPort, newMcpPort]);
+    for (const p of extraPorts) allPorts.add(Number(p));
+
     const deadline = Date.now() + 15_000;
     while (Date.now() < deadline) {
-      const webBusy = await isPortInUse(webPort);
-      const mcpBusy = await isPortInUse(mcpPort);
-      if (!webBusy && !mcpBusy) break;
+      let anyBusy = false;
+      for (const p of allPorts) {
+        if (await isPortInUse(p)) { anyBusy = true; break; }
+      }
+      if (!anyBusy) break;
       await new Promise((r) => setTimeout(r, 500));
     }
     await commands[getStartMode()]();

package/bin/lib/build.js

@@ -65,6 +65,17 @@ function writeDepsStamp() {
   }
 }
 
+/** Critical packages that must exist after npm install for the app to work. */
+const CRITICAL_DEPS = ['next', '@next/env', 'react', 'react-dom'];
+
+function verifyDeps() {
+  const nm = resolve(ROOT, 'app', 'node_modules');
+  for (const dep of CRITICAL_DEPS) {
+    if (!existsSync(resolve(nm, dep, 'package.json'))) return false;
+  }
+  return true;
+}
+
 export function ensureAppDeps() {
   const appNext = resolve(ROOT, 'app', 'node_modules', 'next', 'package.json');
   const needsInstall = !existsSync(appNext) || depsChanged();
@@ -90,5 +101,19 @@ export function ensureAppDeps() {
     : 'Installing app dependencies (first run)...\n';
   console.log(yellow(label));
   run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+
+  // Verify critical deps — npm tar extraction can silently fail (ENOENT race)
+  if (!verifyDeps()) {
+    console.log(yellow('Some dependencies are incomplete, retrying with clean install...\n'));
+    const nm = resolve(ROOT, 'app', 'node_modules');
+    rmSync(nm, { recursive: true, force: true });
+    run('npm install --no-workspaces', resolve(ROOT, 'app'));
+    if (!verifyDeps()) {
+      console.error(red('\n✘ Failed to install dependencies after retry.\n'));
+      console.error('  Try manually: cd ' + resolve(ROOT, 'app') + ' && rm -rf node_modules && npm install');
+      process.exit(1);
+    }
+  }
+
   writeDepsStamp();
 }

package/bin/lib/mcp-agents.js

@@ -1,16 +1,119 @@
 /**
  * Shared MCP agent definitions for CLI tools.
  * Mirrors app/lib/mcp-agents.ts — keep in sync manually.
+ *
+ * Each agent entry includes presenceCli / presenceDirs for detecting
+ * whether the agent is installed on the user's machine. To add a new
+ * agent, add a single entry here — no separate table needed.
  */
 
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+function expandHome(p) {
+  return p.startsWith('~/') ? resolve(homedir(), p.slice(2)) : p;
+}
+
 export const MCP_AGENTS = {
-  'claude-code':    { name: 'Claude Code',    project: '.mcp.json',                       global: '~/.claude.json',                                                                         key: 'mcpServers', preferredTransport: 'stdio' },
-  'claude-desktop': { name: 'Claude Desktop', project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Claude/claude_desktop_config.json' : '~/.config/Claude/claude_desktop_config.json', key: 'mcpServers', preferredTransport: 'http' },
-  'cursor':         { name: 'Cursor',          project: '.cursor/mcp.json',                global: '~/.cursor/mcp.json',                                                                     key: 'mcpServers', preferredTransport: 'stdio' },
-  'windsurf':       { name: 'Windsurf',        project: null,                               global: '~/.codeium/windsurf/mcp_config.json',                                                   key: 'mcpServers', preferredTransport: 'stdio' },
-  'cline':          { name: 'Cline',           project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json' : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json', key: 'mcpServers', preferredTransport: 'stdio' },
-  'trae':           { name: 'Trae',            project: '.trae/mcp.json',                  global: '~/.trae/mcp.json',                                                                       key: 'mcpServers', preferredTransport: 'stdio' },
-  'gemini-cli':     { name: 'Gemini CLI',      project: '.gemini/settings.json',           global: '~/.gemini/settings.json',                                                                key: 'mcpServers', preferredTransport: 'stdio' },
-  'openclaw':       { name: 'OpenClaw',        project: null,                               global: '~/.openclaw/mcp.json',                                                                   key: 'mcpServers', preferredTransport: 'stdio' },
-  'codebuddy':      { name: 'CodeBuddy',       project: null,                               global: '~/.claude-internal/.claude.json',                                                        key: 'mcpServers', preferredTransport: 'stdio' },
+  'claude-code': {
+    name: 'Claude Code',
+    project: '.mcp.json',
+    global: '~/.claude.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'claude',
+    presenceDirs: ['~/.claude/'],
+  },
+  'claude-desktop': {
+    name: 'Claude Desktop',
+    project: null,
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Claude/claude_desktop_config.json'
+      : '~/.config/Claude/claude_desktop_config.json',
+    key: 'mcpServers',
+    preferredTransport: 'http',
+    presenceDirs: ['~/Library/Application Support/Claude/', '~/.config/Claude/'],
+  },
+  'cursor': {
+    name: 'Cursor',
+    project: '.cursor/mcp.json',
+    global: '~/.cursor/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.cursor/'],
+  },
+  'windsurf': {
+    name: 'Windsurf',
+    project: null,
+    global: '~/.codeium/windsurf/mcp_config.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.codeium/windsurf/'],
+  },
+  'cline': {
+    name: 'Cline',
+    project: null,
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
+      : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/',
+      '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/',
+    ],
+  },
+  'trae': {
+    name: 'Trae',
+    project: '.trae/mcp.json',
+    global: '~/.trae/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: ['~/.trae/'],
+  },
+  'gemini-cli': {
+    name: 'Gemini CLI',
+    project: '.gemini/settings.json',
+    global: '~/.gemini/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'gemini',
+    presenceDirs: ['~/.gemini/'],
+  },
+  'openclaw': {
+    name: 'OpenClaw',
+    project: null,
+    global: '~/.openclaw/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'openclaw',
+    presenceDirs: ['~/.openclaw/'],
+  },
+  'codebuddy': {
+    name: 'CodeBuddy',
+    project: null,
+    global: '~/.claude-internal/.claude.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'claude-internal',
+    presenceDirs: ['~/.claude-internal/'],
+  },
 };
+
+export function detectAgentPresence(agentKey) {
+  const agent = MCP_AGENTS[agentKey];
+  if (!agent) return false;
+  if (agent.presenceCli) {
+    try {
+      execSync(
+        process.platform === 'win32' ? `where ${agent.presenceCli}` : `which ${agent.presenceCli}`,
+        { stdio: 'pipe' },
+      );
+      return true;
+    } catch { /* not found */ }
+  }
+  if (agent.presenceDirs?.some(d => existsSync(expandHome(d)))) return true;
+  return false;
+}