claude-brain 0.15.2 → 0.16.0

package/src/cli/commands/chroma.ts

@@ -1,573 +1,573 @@
-/**
- * ChromaDB Management Command
- * Start, stop, and manage the ChromaDB server for Claude Brain
- */
-
-import { spawn, execSync } from 'node:child_process'
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
-import { join } from 'node:path'
-import { getHomePaths } from '@/config/home'
-import {
-  theme, heading, successText, errorText, warningText, dimText,
-  infoPanel,
-} from '@/cli/ui/index.js'
-
-const PID_FILENAME = 'chroma.pid'
-const DEFAULT_PORT = '8000'
-
-function getPidFilePath(): string {
-  const paths = getHomePaths()
-  return join(paths.data, PID_FILENAME)
-}
-
-function getChromaDataPath(): string {
-  const paths = getHomePaths()
-  return paths.chroma
-}
-
-/**
- * Find the chroma binary - checks PATH first, then common pip install locations
- */
-function findChromaBinary(): string | null {
-  const isWindows = process.platform === 'win32'
-  const chromaName = isWindows ? 'chroma.exe' : 'chroma'
-
-  // Try bare 'chroma' first (on PATH)
-  try {
-    execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
-    return 'chroma'
-  } catch {}
-
-  const { homedir } = require('os')
-  const home = homedir()
-
-  // Platform-specific search paths
-  const candidates: string[] = isWindows
-    ? [
-        // Windows pip install locations
-        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python39', 'Scripts', chromaName),
-        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python310', 'Scripts', chromaName),
-        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python311', 'Scripts', chromaName),
-        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python312', 'Scripts', chromaName),
-        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python313', 'Scripts', chromaName),
-        // Windows user pip install (pip install --user)
-        join(home, 'AppData', 'Roaming', 'Python', 'Python39', 'Scripts', chromaName),
-        join(home, 'AppData', 'Roaming', 'Python', 'Python310', 'Scripts', chromaName),
-        join(home, 'AppData', 'Roaming', 'Python', 'Python311', 'Scripts', chromaName),
-        join(home, 'AppData', 'Roaming', 'Python', 'Python312', 'Scripts', chromaName),
-        join(home, 'AppData', 'Roaming', 'Python', 'Python313', 'Scripts', chromaName),
-        // Scoop / Chocolatey / winget
-        join(home, 'scoop', 'shims', chromaName),
-        'C:\\Python39\\Scripts\\' + chromaName,
-        'C:\\Python310\\Scripts\\' + chromaName,
-        'C:\\Python311\\Scripts\\' + chromaName,
-        'C:\\Python312\\Scripts\\' + chromaName,
-        'C:\\Python313\\Scripts\\' + chromaName,
-      ]
-    : [
-        // macOS pip install locations
-        join(home, 'Library', 'Python', '3.9', 'bin', chromaName),
-        join(home, 'Library', 'Python', '3.10', 'bin', chromaName),
-        join(home, 'Library', 'Python', '3.11', 'bin', chromaName),
-        join(home, 'Library', 'Python', '3.12', 'bin', chromaName),
-        join(home, 'Library', 'Python', '3.13', 'bin', chromaName),
-        // Linux pip install locations
-        join(home, '.local', 'bin', chromaName),
-        '/usr/local/bin/' + chromaName,
-        '/opt/homebrew/bin/' + chromaName,
-      ]
-
-  for (const candidate of candidates) {
-    try {
-      if (existsSync(candidate)) {
-        execSync(`"${candidate}" --version`, { stdio: 'pipe', timeout: 5000 })
-        return candidate
-      }
-    } catch {}
-  }
-
-  // Try finding via python -m site (works on all platforms)
-  const pythonCmd = isWindows ? 'python' : 'python3'
-  try {
-    const sitePackages = execSync(`${pythonCmd} -c "import site; print(site.getusersitepackages())"`, {
-      encoding: 'utf-8', stdio: 'pipe', timeout: 5000
-    }).trim()
-
-    let binDir: string
-    if (isWindows) {
-      // Windows: C:\Users\x\AppData\Roaming\Python\Python311\site-packages → Scripts
-      binDir = sitePackages.replace(/[\\\/]site-packages$/, '\\Scripts')
-    } else {
-      // Unix: /Users/x/Library/Python/3.9/lib/python/site-packages → bin
-      binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
-    }
-
-    const chromaPath = join(binDir, chromaName)
-    if (existsSync(chromaPath)) {
-      execSync(`"${chromaPath}" --version`, { stdio: 'pipe', timeout: 5000 })
-      return chromaPath
-    }
-  } catch {}
-
-  return null
-}
-
-let _cachedChromaBinary: string | null | undefined = undefined
-
-function getChromaBinary(): string | null {
-  if (_cachedChromaBinary === undefined) {
-    _cachedChromaBinary = findChromaBinary()
-  }
-  return _cachedChromaBinary
-}
-
-function isChromaCliInstalled(): boolean {
-  return getChromaBinary() !== null
-}
-
-function getChromaVersion(): string {
-  const binary = getChromaBinary()
-  if (!binary) return 'unknown'
-  try {
-    return execSync(`"${binary}" --version`, { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
-  } catch {
-    return 'unknown'
-  }
-}
-
-function isPythonInstalled(): { installed: boolean; cmd: string } {
-  for (const cmd of ['python3', 'python']) {
-    try {
-      execSync(`${cmd} --version`, { stdio: 'pipe', timeout: 5000 })
-      return { installed: true, cmd }
-    } catch {
-      // try next
-    }
-  }
-  return { installed: false, cmd: 'python3' }
-}
-
-function getRunningPid(): number | null {
-  const pidPath = getPidFilePath()
-  if (!existsSync(pidPath)) return null
-
-  try {
-    const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
-    if (isNaN(pid)) {
-      unlinkSync(pidPath)
-      return null
-    }
-    // Signal 0 tests if process exists without killing it
-    process.kill(pid, 0)
-    return pid
-  } catch {
-    // Process not running, clean up stale PID file
-    try { unlinkSync(pidPath) } catch {}
-    return null
-  }
-}
-
-function isChromaReachable(): boolean {
-  // Try v2 API first (ChromaDB 1.x server), then v1 (older servers)
-  for (const apiVersion of ['v2', 'v1']) {
-    try {
-      execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/${apiVersion}/heartbeat`, {
-        stdio: 'pipe',
-        timeout: 3000
-      })
-      return true
-    } catch {}
-  }
-  return false
-}
-
-async function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
-
-// ── Subcommands ───────────────────────────────────────────
-
-async function chromaStart(): Promise<void> {
-  console.log()
-  console.log(heading('Starting ChromaDB Server'))
-  console.log()
-
-  // Check if already running
-  const existingPid = getRunningPid()
-  if (existingPid) {
-    console.log(warningText(`ChromaDB is already running (PID: ${existingPid})`))
-    console.log()
-    return
-  }
-
-  if (isChromaReachable()) {
-    console.log(warningText('A ChromaDB server is already running on port ' + DEFAULT_PORT))
-    console.log()
-    return
-  }
-
-  // Check if chroma CLI is installed
-  const chromaBinary = getChromaBinary()
-  if (!chromaBinary) {
-    console.log(errorText('ChromaDB CLI is not installed or not found on PATH.'))
-    console.log()
-    console.log(dimText('Install it with:'))
-    console.log(`  ${theme.primary('pip install chromadb')}`)
-    console.log()
-    console.log(dimText('Or run:'))
-    console.log(`  ${theme.primary('claude-brain chroma install')}`)
-    console.log()
-    process.exit(1)
-  }
-
-  const dataPath = getChromaDataPath()
-
-  console.log(dimText(`Binary: ${chromaBinary}`))
-  console.log(dimText(`Data path: ${dataPath}`))
-  console.log(dimText(`Port: ${DEFAULT_PORT}`))
-  console.log()
-
-  // Start ChromaDB server in background
-  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
-    detached: true,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: { ...process.env }
-  })
-
-  const pid = child.pid
-  if (!pid) {
-    console.log(errorText('Failed to start ChromaDB server — no PID returned.'))
-    console.log()
-    process.exit(1)
-  }
-
-  // Detach the child process so it runs independently
-  child.unref()
-
-  // Save PID file
-  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
-
-  // Capture early output for error detection
-  let startupOutput = ''
-  child.stderr?.on('data', (chunk: Buffer) => {
-    startupOutput += chunk.toString()
-  })
-  child.stdout?.on('data', (chunk: Buffer) => {
-    startupOutput += chunk.toString()
-  })
-
-  // Wait up to 15 seconds for server to become reachable
-  let ready = false
-  for (let i = 0; i < 30; i++) {
-    await sleep(500)
-    if (isChromaReachable()) {
-      ready = true
-      break
-    }
-    // Check if process exited early
-    try {
-      process.kill(pid, 0)
-    } catch {
-      break
-    }
-  }
-
-  if (ready) {
-    console.log(successText(`ChromaDB server started (PID: ${pid})`))
-    console.log()
-    console.log(dimText('The server is running in the background.'))
-    console.log(dimText('Stop it with: ') + theme.primary('claude-brain chroma stop'))
-  } else {
-    // Check if process is still alive
-    let alive = false
-    try {
-      process.kill(pid, 0)
-      alive = true
-    } catch {}
-
-    if (alive) {
-      console.log(warningText('ChromaDB server started but not yet responding.'))
-      console.log(dimText(`PID: ${pid} — it may still be initializing.`))
-      console.log(dimText('Check with: ') + theme.primary('claude-brain chroma status'))
-    } else {
-      console.log(errorText('ChromaDB server failed to start.'))
-      if (startupOutput) {
-        console.log(dimText('Output:'))
-        console.log(dimText(startupOutput.slice(0, 500)))
-      }
-      try { unlinkSync(getPidFilePath()) } catch {}
-      process.exit(1)
-    }
-  }
-  console.log()
-}
-
-async function chromaStop(): Promise<void> {
-  console.log()
-  console.log(heading('Stopping ChromaDB Server'))
-  console.log()
-
-  const pid = getRunningPid()
-  if (!pid) {
-    if (isChromaReachable()) {
-      console.log(warningText('A ChromaDB server is running on port ' + DEFAULT_PORT + ' but was not started by claude-brain.'))
-      console.log(dimText('Kill it manually if needed.'))
-    } else {
-      console.log(dimText('No ChromaDB server is currently running.'))
-    }
-    console.log()
-    return
-  }
-
-  try {
-    process.kill(pid, 'SIGTERM')
-
-    // Wait up to 5 seconds for graceful shutdown
-    for (let i = 0; i < 10; i++) {
-      await sleep(500)
-      try {
-        process.kill(pid, 0)
-      } catch {
-        // Process exited
-        break
-      }
-    }
-
-    // Force kill if still running
-    try {
-      process.kill(pid, 0)
-      // Still alive, force kill
-      process.kill(pid, 'SIGKILL')
-    } catch {
-      // Already dead, good
-    }
-
-    try { unlinkSync(getPidFilePath()) } catch {}
-
-    console.log(successText(`ChromaDB server stopped (PID: ${pid})`))
-  } catch (error) {
-    console.log(errorText(`Failed to stop ChromaDB: ${error instanceof Error ? error.message : String(error)}`))
-    try { unlinkSync(getPidFilePath()) } catch {}
-  }
-  console.log()
-}
-
-async function chromaStatus(): Promise<void> {
-  console.log()
-
-  const pid = getRunningPid()
-  const reachable = isChromaReachable()
-  const installed = isChromaCliInstalled()
-  const version = installed ? getChromaVersion() : 'N/A'
-  const dataPath = getChromaDataPath()
-  const dataExists = existsSync(dataPath)
-
-  const items: Record<string, string> = {
-    'Installed': installed ? `Yes (${version})` : 'No',
-    'Server': reachable ? `Running (port ${DEFAULT_PORT})` : 'Not running',
-    'Managed PID': pid ? String(pid) : 'None',
-    'Data Path': dataPath,
-    'Data Exists': dataExists ? 'Yes' : 'No',
-  }
-
-  console.log(infoPanel('ChromaDB Status', items))
-
-  if (!installed) {
-    console.log()
-    console.log(warningText('ChromaDB is not installed.'))
-    console.log(dimText('Install with: ') + theme.primary('claude-brain chroma install'))
-  } else if (!reachable) {
-    console.log()
-    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
-  }
-  console.log()
-}
-
-async function chromaInstall(): Promise<void> {
-  console.log()
-  console.log(heading('Installing ChromaDB'))
-  console.log()
-
-  if (isChromaCliInstalled()) {
-    const version = getChromaVersion()
-    console.log(successText(`ChromaDB is already installed (${version}).`))
-    console.log()
-    return
-  }
-
-  const python = isPythonInstalled()
-  if (!python.installed) {
-    console.log(errorText('Python 3 is required to install ChromaDB.'))
-    console.log()
-    console.log(dimText('Install Python 3 first:'))
-    console.log(`  ${theme.primary('macOS:')}   brew install python3`)
-    console.log(`  ${theme.primary('Ubuntu:')}  sudo apt install python3 python3-pip`)
-    console.log(`  ${theme.primary('Windows:')} https://python.org/downloads`)
-    console.log()
-    process.exit(1)
-  }
-
-  console.log(dimText(`Found ${python.cmd}. Installing chromadb via pip...`))
-  console.log()
-
-  const pipCommands = python.cmd === 'python3'
-    ? ['pip3 install chromadb', 'python3 -m pip install chromadb']
-    : ['pip install chromadb', 'python -m pip install chromadb']
-
-  let installed = false
-  for (const cmd of pipCommands) {
-    try {
-      execSync(cmd, { stdio: 'inherit', timeout: 300_000 })
-      installed = true
-      break
-    } catch {
-      // Try next command
-    }
-  }
-
-  console.log()
-  if (installed) {
-    console.log(successText('ChromaDB installed successfully!'))
-    console.log()
-    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
-  } else {
-    console.log(errorText('Failed to install ChromaDB.'))
-    console.log(dimText('Try installing manually:'))
-    console.log(`  ${theme.primary('pip install chromadb')}`)
-    process.exit(1)
-  }
-  console.log()
-}
-
-// ── Help ──────────────────────────────────────────────────
-
-function printChromaHelp(): void {
-  console.log()
-  console.log(heading('ChromaDB Management'))
-  console.log()
-  console.log(dimText('ChromaDB provides vector storage for semantic search,'))
-  console.log(dimText('knowledge graph, and advanced intelligence features.'))
-  console.log()
-
-  const commands = [
-    ['start', 'Start ChromaDB server in background'],
-    ['stop', 'Stop the running ChromaDB server'],
-    ['status', 'Show ChromaDB server status'],
-    ['install', 'Install ChromaDB (requires Python 3)'],
-  ]
-
-  const cmdLines = commands
-    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(12))} ${dimText(desc!)}`)
-    .join('\n')
-
-  console.log(theme.bold('Commands:'))
-  console.log(cmdLines)
-  console.log()
-
-  console.log(theme.bold('Usage:'))
-  console.log(`  ${dimText('claude-brain chroma install')}   ${dimText('Install ChromaDB')}`)
-  console.log(`  ${dimText('claude-brain chroma start')}     ${dimText('Start the server')}`)
-  console.log(`  ${dimText('claude-brain chroma status')}    ${dimText('Check if running')}`)
-  console.log(`  ${dimText('claude-brain chroma stop')}      ${dimText('Stop the server')}`)
-  console.log()
-}
-
-// ── Auto-start for serve command ──────────────────────────
-
-/**
- * Ensures ChromaDB is running before the MCP server starts.
- * Returns true if ChromaDB is reachable after this call, false otherwise.
- * Designed to be called from serve.ts — does not call process.exit().
- */
-export async function ensureChromaRunning(options?: { silent?: boolean }): Promise<boolean> {
-  const log = options?.silent ? () => {} : console.error.bind(console)
-
-  // Already running? Great.
-  if (isChromaReachable()) {
-    return true
-  }
-
-  // Already managed by us but not responding? Clean up stale PID.
-  const stalePid = getRunningPid()
-  if (stalePid) {
-    try {
-      process.kill(stalePid, 'SIGTERM')
-      await sleep(1000)
-    } catch {}
-    try { unlinkSync(getPidFilePath()) } catch {}
-  }
-
-  const chromaBinary = getChromaBinary()
-  if (!chromaBinary) {
-    log('[ChromaDB] Not installed — running with SQLite fallback.')
-    log('[ChromaDB] Install with: claude-brain chroma install')
-    return false
-  }
-
-  const dataPath = getChromaDataPath()
-  log(`[ChromaDB] Starting server (port ${DEFAULT_PORT})...`)
-
-  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
-    detached: true,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: { ...process.env }
-  })
-
-  const pid = child.pid
-  if (!pid) {
-    log('[ChromaDB] Failed to spawn server process.')
-    return false
-  }
-
-  child.unref()
-  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
-
-  // Wait for server to become reachable (up to 15 seconds)
-  for (let i = 0; i < 30; i++) {
-    await sleep(500)
-    if (isChromaReachable()) {
-      log(`[ChromaDB] Server started (PID: ${pid})`)
-      return true
-    }
-    // Check if process died
-    try {
-      process.kill(pid, 0)
-    } catch {
-      break
-    }
-  }
-
-  log('[ChromaDB] Server started but not yet responding — will retry connection during initialization.')
-  return isChromaReachable()
-}
-
-// ── Entry Point ───────────────────────────────────────────
-
-export async function runChroma(): Promise<void> {
-  const subcommand = process.argv[3] || 'help'
-
-  switch (subcommand) {
-    case 'start':
-      await chromaStart()
-      break
-    case 'stop':
-      await chromaStop()
-      break
-    case 'status':
-      await chromaStatus()
-      break
-    case 'install':
-      await chromaInstall()
-      break
-    case 'help':
-    case '--help':
-    case '-h':
-      printChromaHelp()
-      break
-    default:
-      console.log()
-      console.log(errorText(`Unknown subcommand: ${subcommand}`))
-      printChromaHelp()
-      process.exit(1)
-  }
-}
+/**
+ * ChromaDB Management Command
+ * Start, stop, and manage the ChromaDB server for Claude Brain
+ */
+
+import { spawn, execSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { getHomePaths } from '@/config/home'
+import {
+  theme, heading, successText, errorText, warningText, dimText,
+  infoPanel,
+} from '@/cli/ui/index.js'
+
+const PID_FILENAME = 'chroma.pid'
+const DEFAULT_PORT = '8000'
+
+function getPidFilePath(): string {
+  const paths = getHomePaths()
+  return join(paths.data, PID_FILENAME)
+}
+
+function getChromaDataPath(): string {
+  const paths = getHomePaths()
+  return paths.chroma
+}
+
+/**
+ * Find the chroma binary - checks PATH first, then common pip install locations
+ */
+function findChromaBinary(): string | null {
+  const isWindows = process.platform === 'win32'
+  const chromaName = isWindows ? 'chroma.exe' : 'chroma'
+
+  // Try bare 'chroma' first (on PATH)
+  try {
+    execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
+    return 'chroma'
+  } catch {}
+
+  const { homedir } = require('os')
+  const home = homedir()
+
+  // Platform-specific search paths
+  const candidates: string[] = isWindows
+    ? [
+        // Windows pip install locations
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python313', 'Scripts', chromaName),
+        // Windows user pip install (pip install --user)
+        join(home, 'AppData', 'Roaming', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python313', 'Scripts', chromaName),
+        // Scoop / Chocolatey / winget
+        join(home, 'scoop', 'shims', chromaName),
+        'C:\\Python39\\Scripts\\' + chromaName,
+        'C:\\Python310\\Scripts\\' + chromaName,
+        'C:\\Python311\\Scripts\\' + chromaName,
+        'C:\\Python312\\Scripts\\' + chromaName,
+        'C:\\Python313\\Scripts\\' + chromaName,
+      ]
+    : [
+        // macOS pip install locations
+        join(home, 'Library', 'Python', '3.9', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.10', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.11', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.12', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.13', 'bin', chromaName),
+        // Linux pip install locations
+        join(home, '.local', 'bin', chromaName),
+        '/usr/local/bin/' + chromaName,
+        '/opt/homebrew/bin/' + chromaName,
+      ]
+
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate)) {
+        execSync(`"${candidate}" --version`, { stdio: 'pipe', timeout: 5000 })
+        return candidate
+      }
+    } catch {}
+  }
+
+  // Try finding via python -m site (works on all platforms)
+  const pythonCmd = isWindows ? 'python' : 'python3'
+  try {
+    const sitePackages = execSync(`${pythonCmd} -c "import site; print(site.getusersitepackages())"`, {
+      encoding: 'utf-8', stdio: 'pipe', timeout: 5000
+    }).trim()
+
+    let binDir: string
+    if (isWindows) {
+      // Windows: C:\Users\x\AppData\Roaming\Python\Python311\site-packages → Scripts
+      binDir = sitePackages.replace(/[\\\/]site-packages$/, '\\Scripts')
+    } else {
+      // Unix: /Users/x/Library/Python/3.9/lib/python/site-packages → bin
+      binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
+    }
+
+    const chromaPath = join(binDir, chromaName)
+    if (existsSync(chromaPath)) {
+      execSync(`"${chromaPath}" --version`, { stdio: 'pipe', timeout: 5000 })
+      return chromaPath
+    }
+  } catch {}
+
+  return null
+}
+
+let _cachedChromaBinary: string | null | undefined = undefined
+
+function getChromaBinary(): string | null {
+  if (_cachedChromaBinary === undefined) {
+    _cachedChromaBinary = findChromaBinary()
+  }
+  return _cachedChromaBinary
+}
+
+function isChromaCliInstalled(): boolean {
+  return getChromaBinary() !== null
+}
+
+function getChromaVersion(): string {
+  const binary = getChromaBinary()
+  if (!binary) return 'unknown'
+  try {
+    return execSync(`"${binary}" --version`, { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+function isPythonInstalled(): { installed: boolean; cmd: string } {
+  for (const cmd of ['python3', 'python']) {
+    try {
+      execSync(`${cmd} --version`, { stdio: 'pipe', timeout: 5000 })
+      return { installed: true, cmd }
+    } catch {
+      // try next
+    }
+  }
+  return { installed: false, cmd: 'python3' }
+}
+
+function getRunningPid(): number | null {
+  const pidPath = getPidFilePath()
+  if (!existsSync(pidPath)) return null
+
+  try {
+    const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
+    if (isNaN(pid)) {
+      unlinkSync(pidPath)
+      return null
+    }
+    // Signal 0 tests if process exists without killing it
+    process.kill(pid, 0)
+    return pid
+  } catch {
+    // Process not running, clean up stale PID file
+    try { unlinkSync(pidPath) } catch {}
+    return null
+  }
+}
+
+function isChromaReachable(): boolean {
+  // Try v2 API first (ChromaDB 1.x server), then v1 (older servers)
+  for (const apiVersion of ['v2', 'v1']) {
+    try {
+      execSync(`curl -sf http://localhost:${DEFAULT_PORT}/api/${apiVersion}/heartbeat`, {
+        stdio: 'pipe',
+        timeout: 3000
+      })
+      return true
+    } catch {}
+  }
+  return false
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// ── Subcommands ───────────────────────────────────────────
+
+async function chromaStart(): Promise<void> {
+  console.log()
+  console.log(heading('Starting ChromaDB Server'))
+  console.log()
+
+  // Check if already running
+  const existingPid = getRunningPid()
+  if (existingPid) {
+    console.log(warningText(`ChromaDB is already running (PID: ${existingPid})`))
+    console.log()
+    return
+  }
+
+  if (isChromaReachable()) {
+    console.log(warningText('A ChromaDB server is already running on port ' + DEFAULT_PORT))
+    console.log()
+    return
+  }
+
+  // Check if chroma CLI is installed
+  const chromaBinary = getChromaBinary()
+  if (!chromaBinary) {
+    console.log(errorText('ChromaDB CLI is not installed or not found on PATH.'))
+    console.log()
+    console.log(dimText('Install it with:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    console.log()
+    console.log(dimText('Or run:'))
+    console.log(`  ${theme.primary('claude-brain chroma install')}`)
+    console.log()
+    process.exit(1)
+  }
+
+  const dataPath = getChromaDataPath()
+
+  console.log(dimText(`Binary: ${chromaBinary}`))
+  console.log(dimText(`Data path: ${dataPath}`))
+  console.log(dimText(`Port: ${DEFAULT_PORT}`))
+  console.log()
+
+  // Start ChromaDB server in background
+  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env }
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    console.log(errorText('Failed to start ChromaDB server — no PID returned.'))
+    console.log()
+    process.exit(1)
+  }
+
+  // Detach the child process so it runs independently
+  child.unref()
+
+  // Save PID file
+  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
+
+  // Capture early output for error detection
+  let startupOutput = ''
+  child.stderr?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+  child.stdout?.on('data', (chunk: Buffer) => {
+    startupOutput += chunk.toString()
+  })
+
+  // Wait up to 15 seconds for server to become reachable
+  let ready = false
+  for (let i = 0; i < 30; i++) {
+    await sleep(500)
+    if (isChromaReachable()) {
+      ready = true
+      break
+    }
+    // Check if process exited early
+    try {
+      process.kill(pid, 0)
+    } catch {
+      break
+    }
+  }
+
+  if (ready) {
+    console.log(successText(`ChromaDB server started (PID: ${pid})`))
+    console.log()
+    console.log(dimText('The server is running in the background.'))
+    console.log(dimText('Stop it with: ') + theme.primary('claude-brain chroma stop'))
+  } else {
+    // Check if process is still alive
+    let alive = false
+    try {
+      process.kill(pid, 0)
+      alive = true
+    } catch {}
+
+    if (alive) {
+      console.log(warningText('ChromaDB server started but not yet responding.'))
+      console.log(dimText(`PID: ${pid} — it may still be initializing.`))
+      console.log(dimText('Check with: ') + theme.primary('claude-brain chroma status'))
+    } else {
+      console.log(errorText('ChromaDB server failed to start.'))
+      if (startupOutput) {
+        console.log(dimText('Output:'))
+        console.log(dimText(startupOutput.slice(0, 500)))
+      }
+      try { unlinkSync(getPidFilePath()) } catch {}
+      process.exit(1)
+    }
+  }
+  console.log()
+}
+
+async function chromaStop(): Promise<void> {
+  console.log()
+  console.log(heading('Stopping ChromaDB Server'))
+  console.log()
+
+  const pid = getRunningPid()
+  if (!pid) {
+    if (isChromaReachable()) {
+      console.log(warningText('A ChromaDB server is running on port ' + DEFAULT_PORT + ' but was not started by claude-brain.'))
+      console.log(dimText('Kill it manually if needed.'))
+    } else {
+      console.log(dimText('No ChromaDB server is currently running.'))
+    }
+    console.log()
+    return
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM')
+
+    // Wait up to 5 seconds for graceful shutdown
+    for (let i = 0; i < 10; i++) {
+      await sleep(500)
+      try {
+        process.kill(pid, 0)
+      } catch {
+        // Process exited
+        break
+      }
+    }
+
+    // Force kill if still running
+    try {
+      process.kill(pid, 0)
+      // Still alive, force kill
+      process.kill(pid, 'SIGKILL')
+    } catch {
+      // Already dead, good
+    }
+
+    try { unlinkSync(getPidFilePath()) } catch {}
+
+    console.log(successText(`ChromaDB server stopped (PID: ${pid})`))
+  } catch (error) {
+    console.log(errorText(`Failed to stop ChromaDB: ${error instanceof Error ? error.message : String(error)}`))
+    try { unlinkSync(getPidFilePath()) } catch {}
+  }
+  console.log()
+}
+
+async function chromaStatus(): Promise<void> {
+  console.log()
+
+  const pid = getRunningPid()
+  const reachable = isChromaReachable()
+  const installed = isChromaCliInstalled()
+  const version = installed ? getChromaVersion() : 'N/A'
+  const dataPath = getChromaDataPath()
+  const dataExists = existsSync(dataPath)
+
+  const items: Record<string, string> = {
+    'Installed': installed ? `Yes (${version})` : 'No',
+    'Server': reachable ? `Running (port ${DEFAULT_PORT})` : 'Not running',
+    'Managed PID': pid ? String(pid) : 'None',
+    'Data Path': dataPath,
+    'Data Exists': dataExists ? 'Yes' : 'No',
+  }
+
+  console.log(infoPanel('ChromaDB Status', items))
+
+  if (!installed) {
+    console.log()
+    console.log(warningText('ChromaDB is not installed.'))
+    console.log(dimText('Install with: ') + theme.primary('claude-brain chroma install'))
+  } else if (!reachable) {
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  }
+  console.log()
+}
+
+async function chromaInstall(): Promise<void> {
+  console.log()
+  console.log(heading('Installing ChromaDB'))
+  console.log()
+
+  if (isChromaCliInstalled()) {
+    const version = getChromaVersion()
+    console.log(successText(`ChromaDB is already installed (${version}).`))
+    console.log()
+    return
+  }
+
+  const python = isPythonInstalled()
+  if (!python.installed) {
+    console.log(errorText('Python 3 is required to install ChromaDB.'))
+    console.log()
+    console.log(dimText('Install Python 3 first:'))
+    console.log(`  ${theme.primary('macOS:')}   brew install python3`)
+    console.log(`  ${theme.primary('Ubuntu:')}  sudo apt install python3 python3-pip`)
+    console.log(`  ${theme.primary('Windows:')} https://python.org/downloads`)
+    console.log()
+    process.exit(1)
+  }
+
+  console.log(dimText(`Found ${python.cmd}. Installing chromadb via pip...`))
+  console.log()
+
+  const pipCommands = python.cmd === 'python3'
+    ? ['pip3 install chromadb', 'python3 -m pip install chromadb']
+    : ['pip install chromadb', 'python -m pip install chromadb']
+
+  let installed = false
+  for (const cmd of pipCommands) {
+    try {
+      execSync(cmd, { stdio: 'inherit', timeout: 300_000 })
+      installed = true
+      break
+    } catch {
+      // Try next command
+    }
+  }
+
+  console.log()
+  if (installed) {
+    console.log(successText('ChromaDB installed successfully!'))
+    console.log()
+    console.log(dimText('Start the server with: ') + theme.primary('claude-brain chroma start'))
+  } else {
+    console.log(errorText('Failed to install ChromaDB.'))
+    console.log(dimText('Try installing manually:'))
+    console.log(`  ${theme.primary('pip install chromadb')}`)
+    process.exit(1)
+  }
+  console.log()
+}
+
+// ── Help ──────────────────────────────────────────────────
+
+function printChromaHelp(): void {
+  console.log()
+  console.log(heading('ChromaDB Management'))
+  console.log()
+  console.log(dimText('ChromaDB provides vector storage for semantic search,'))
+  console.log(dimText('knowledge graph, and advanced intelligence features.'))
+  console.log()
+
+  const commands = [
+    ['start', 'Start ChromaDB server in background'],
+    ['stop', 'Stop the running ChromaDB server'],
+    ['status', 'Show ChromaDB server status'],
+    ['install', 'Install ChromaDB (requires Python 3)'],
+  ]
+
+  const cmdLines = commands
+    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(12))} ${dimText(desc!)}`)
+    .join('\n')
+
+  console.log(theme.bold('Commands:'))
+  console.log(cmdLines)
+  console.log()
+
+  console.log(theme.bold('Usage:'))
+  console.log(`  ${dimText('claude-brain chroma install')}   ${dimText('Install ChromaDB')}`)
+  console.log(`  ${dimText('claude-brain chroma start')}     ${dimText('Start the server')}`)
+  console.log(`  ${dimText('claude-brain chroma status')}    ${dimText('Check if running')}`)
+  console.log(`  ${dimText('claude-brain chroma stop')}      ${dimText('Stop the server')}`)
+  console.log()
+}
+
+// ── Auto-start for serve command ──────────────────────────
+
+/**
+ * Ensures ChromaDB is running before the MCP server starts.
+ * Returns true if ChromaDB is reachable after this call, false otherwise.
+ * Designed to be called from serve.ts — does not call process.exit().
+ */
+export async function ensureChromaRunning(options?: { silent?: boolean }): Promise<boolean> {
+  const log = options?.silent ? () => {} : console.error.bind(console)
+
+  // Already running? Great.
+  if (isChromaReachable()) {
+    return true
+  }
+
+  // Already managed by us but not responding? Clean up stale PID.
+  const stalePid = getRunningPid()
+  if (stalePid) {
+    try {
+      process.kill(stalePid, 'SIGTERM')
+      await sleep(1000)
+    } catch {}
+    try { unlinkSync(getPidFilePath()) } catch {}
+  }
+
+  const chromaBinary = getChromaBinary()
+  if (!chromaBinary) {
+    log('[ChromaDB] Not installed — running with SQLite fallback.')
+    log('[ChromaDB] Install with: claude-brain chroma install')
+    return false
+  }
+
+  const dataPath = getChromaDataPath()
+  log(`[ChromaDB] Starting server (port ${DEFAULT_PORT})...`)
+
+  const child = spawn(chromaBinary, ['run', '--path', dataPath, '--port', DEFAULT_PORT], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env }
+  })
+
+  const pid = child.pid
+  if (!pid) {
+    log('[ChromaDB] Failed to spawn server process.')
+    return false
+  }
+
+  child.unref()
+  writeFileSync(getPidFilePath(), String(pid), 'utf-8')
+
+  // Wait for server to become reachable (up to 15 seconds)
+  for (let i = 0; i < 30; i++) {
+    await sleep(500)
+    if (isChromaReachable()) {
+      log(`[ChromaDB] Server started (PID: ${pid})`)
+      return true
+    }
+    // Check if process died
+    try {
+      process.kill(pid, 0)
+    } catch {
+      break
+    }
+  }
+
+  log('[ChromaDB] Server started but not yet responding — will retry connection during initialization.')
+  return isChromaReachable()
+}
+
+// ── Entry Point ───────────────────────────────────────────
+
+export async function runChroma(): Promise<void> {
+  const subcommand = process.argv[3] || 'help'
+
+  switch (subcommand) {
+    case 'start':
+      await chromaStart()
+      break
+    case 'stop':
+      await chromaStop()
+      break
+    case 'status':
+      await chromaStatus()
+      break
+    case 'install':
+      await chromaInstall()
+      break
+    case 'help':
+    case '--help':
+    case '-h':
+      printChromaHelp()
+      break
+    default:
+      console.log()
+      console.log(errorText(`Unknown subcommand: ${subcommand}`))
+      printChromaHelp()
+      process.exit(1)
+  }
+}