claude-brain 0.23.0 → 0.24.1

package/VERSION

@@ -1 +1 @@
-0.22.4
+0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",

package/scripts/postinstall.mjs

@@ -314,6 +314,80 @@ function installClaudeMd() {
   return true
 }
 
+// ── Step 6: Install auto-start in shell profile ──────────
+
+const AUTO_START_MARKER = '# >>> claude-brain auto-start >>>'
+const AUTO_END_MARKER = '# <<< claude-brain auto-start <<<'
+
+function getShellProfile() {
+  const home = homedir()
+  const os = process.platform
+
+  if (os === 'win32') {
+    const userProfile = process.env.USERPROFILE
+    if (userProfile) {
+      return join(userProfile, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1')
+    }
+    return null
+  }
+
+  // macOS defaults to zsh, Linux to bash
+  return os === 'darwin' ? join(home, '.zshrc') : join(home, '.bashrc')
+}
+
+function buildAutoStartSnippet(profilePath) {
+  if (profilePath && profilePath.endsWith('.ps1')) {
+    return [
+      AUTO_START_MARKER,
+      'if (Get-Command claude-brain -ErrorAction SilentlyContinue) {',
+      '  $listening = Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue',
+      '  if (-not $listening) {',
+      '    Start-Process -NoNewWindow -FilePath "claude-brain" -ArgumentList "serve" -WindowStyle Hidden',
+      '  }',
+      '}',
+      AUTO_END_MARKER,
+    ].join('\n')
+  }
+  return [
+    AUTO_START_MARKER,
+    '# Auto-start claude-brain server if not already running',
+    '(command -v claude-brain >/dev/null 2>&1 && ! lsof -ti :3000 >/dev/null 2>&1) && {',
+    '  nohup claude-brain serve >/dev/null 2>&1 &',
+    '  disown 2>/dev/null',
+    '}',
+    AUTO_END_MARKER,
+  ].join('\n')
+}
+
+function installShellAutoStart() {
+  const profilePath = getShellProfile()
+  if (!profilePath) {
+    log('No supported shell profile found, skipping auto-start')
+    return false
+  }
+
+  // Check if already installed
+  if (existsSync(profilePath)) {
+    const content = readFileSync(profilePath, 'utf-8')
+    if (content.includes(AUTO_START_MARKER)) {
+      log('Auto-start already installed')
+      return true
+    }
+  }
+
+  // Ensure parent directory exists
+  const dir = join(profilePath, '..')
+  mkdirSync(dir, { recursive: true })
+
+  const existing = existsSync(profilePath) ? readFileSync(profilePath, 'utf-8') : ''
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n\n' : '\n'
+  const snippet = buildAutoStartSnippet(profilePath)
+  writeFileSync(profilePath, existing + separator + snippet + '\n', 'utf-8')
+
+  log(`Auto-start installed in ${profilePath}`)
+  return true
+}
+
 // ── Main ─────────────────────────────────────────────────
 
 async function main() {
@@ -332,6 +406,7 @@ async function main() {
     hooks: false,
     hookFiles: false,
     claudemd: false,
+    autostart: false,
   }
 
   // Step 1: Create data directory
@@ -349,15 +424,17 @@ async function main() {
   // Step 5: Install CLAUDE.md
   try { results.claudemd = installClaudeMd() } catch (e) { log(`CLAUDE.md install failed: ${e.message}`) }
 
+  // Step 6: Install auto-start in shell profile
+  try { results.autostart = installShellAutoStart() } catch (e) { log(`Auto-start install failed: ${e.message}`) }
+
   // Print success summary
   console.error('')
   console.error(`${PREFIX} ────────────────────────────────────────`)
   console.error(`${PREFIX}`)
   console.error(`${PREFIX}  Claude Brain installed successfully!`)
   console.error(`${PREFIX}`)
-  console.error(`${PREFIX}  Next steps:`)
-  console.error(`${PREFIX}    1. Start the server:  claude-brain start`)
-  console.error(`${PREFIX}    2. Restart Claude Code to activate hooks`)
+  console.error(`${PREFIX}  Server will auto-start on next terminal session.`)
+  console.error(`${PREFIX}  Auto-updates check every 24h in the background.`)
   console.error(`${PREFIX}`)
   console.error(`${PREFIX}  Data:   ${HOME}/data/`)
   console.error(`${PREFIX}  Config: ${HOME}/config.yml`)
@@ -365,6 +442,7 @@ async function main() {
   console.error(`${PREFIX}`)
   console.error(`${PREFIX}  No setup wizard needed — everything works out of the box.`)
   console.error(`${PREFIX}  ChromaDB is optional (disabled by default, SQLite FTS5 is used).`)
+  console.error(`${PREFIX}  To disable auto-start: claude-brain autostart uninstall`)
   console.error(`${PREFIX} ────────────────────────────────────────`)
   console.error('')
 }

package/src/cli/auto-start.ts

@@ -0,0 +1,266 @@
+/**
+ * Auto-start integration for claude-brain server.
+ * Installs/uninstalls a shell profile snippet so the server
+ * auto-starts on every new terminal session.
+ *
+ * Pure Node.js — no Bun-specific APIs.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir, platform } from 'node:os'
+
+const START_MARKER = '# >>> claude-brain auto-start >>>'
+const END_MARKER = '# <<< claude-brain auto-start <<<'
+
+const PREFIX = '[claude-brain]'
+
+function log(msg: string) {
+  console.error(`${PREFIX} ${msg}`)
+}
+
+export interface AutoStartResult {
+  success: boolean
+  message: string
+  profilePath: string
+}
+
+/**
+ * Build the Unix/macOS/Linux shell snippet.
+ * Uses `lsof` to check if the port is already in use before starting.
+ */
+function buildUnixSnippet(port: number): string {
+  return [
+    START_MARKER,
+    '# Auto-start claude-brain server if not already running',
+    `(command -v claude-brain >/dev/null 2>&1 && ! lsof -ti :${port} >/dev/null 2>&1) && {`,
+    '  nohup claude-brain serve >/dev/null 2>&1 &',
+    '  disown 2>/dev/null',
+    '}',
+    END_MARKER,
+  ].join('\n')
+}
+
+/**
+ * Build the Fish shell snippet.
+ * Fish uses different syntax than bash/zsh.
+ */
+function buildFishSnippet(port: number): string {
+  return [
+    START_MARKER,
+    '# Auto-start claude-brain server if not already running',
+    `if command -v claude-brain >/dev/null 2>&1; and not lsof -ti :${port} >/dev/null 2>&1`,
+    '  nohup claude-brain serve >/dev/null 2>&1 &',
+    'end',
+    END_MARKER,
+  ].join('\n')
+}
+
+/**
+ * Build the PowerShell snippet for Windows.
+ */
+function buildPowerShellSnippet(port: number): string {
+  return [
+    START_MARKER,
+    'if (Get-Command claude-brain -ErrorAction SilentlyContinue) {',
+    `  $port = ${port}`,
+    '  $listening = Get-NetTCPConnection -LocalPort $port -ErrorAction SilentlyContinue',
+    '  if (-not $listening) {',
+    '    Start-Process -NoNewWindow -FilePath "claude-brain" -ArgumentList "serve" -WindowStyle Hidden',
+    '  }',
+    '}',
+    END_MARKER,
+  ].join('\n')
+}
+
+/**
+ * Detect available shell profile files based on platform.
+ * Returns paths that exist or are the primary target for the detected shell.
+ */
+export function getShellProfiles(): string[] {
+  const home = homedir()
+  const os = platform()
+  const profiles: string[] = []
+
+  if (os === 'win32') {
+    // PowerShell profile
+    const psProfile = process.env.USERPROFILE
+      ? join(
+          process.env.USERPROFILE,
+          'Documents',
+          'PowerShell',
+          'Microsoft.PowerShell_profile.ps1'
+        )
+      : null
+    // Also check WindowsPowerShell variant
+    const psProfileLegacy = process.env.USERPROFILE
+      ? join(
+          process.env.USERPROFILE,
+          'Documents',
+          'WindowsPowerShell',
+          'Microsoft.PowerShell_profile.ps1'
+        )
+      : null
+
+    if (psProfile) profiles.push(psProfile)
+    if (psProfileLegacy && psProfileLegacy !== psProfile) profiles.push(psProfileLegacy)
+    return profiles
+  }
+
+  // Unix/macOS/Linux
+  if (os === 'darwin') {
+    // macOS defaults to zsh
+    profiles.push(join(home, '.zshrc'))
+    profiles.push(join(home, '.zprofile'))
+  } else {
+    // Linux defaults to bash
+    profiles.push(join(home, '.bashrc'))
+    profiles.push(join(home, '.bash_profile'))
+  }
+
+  // Fish (cross-platform Unix)
+  const fishConfig = join(home, '.config', 'fish', 'config.fish')
+  if (existsSync(fishConfig)) {
+    profiles.push(fishConfig)
+  }
+
+  return profiles
+}
+
+/**
+ * Check if the auto-start snippet is already in any profile file.
+ */
+function profileContainsSnippet(profilePath: string): boolean {
+  if (!existsSync(profilePath)) return false
+  const content = readFileSync(profilePath, 'utf-8')
+  return content.includes(START_MARKER)
+}
+
+/**
+ * Get the appropriate snippet for a given profile path.
+ */
+function getSnippetForProfile(profilePath: string, port: number): string {
+  if (profilePath.endsWith('.ps1')) {
+    return buildPowerShellSnippet(port)
+  }
+  if (profilePath.includes('fish')) {
+    return buildFishSnippet(port)
+  }
+  return buildUnixSnippet(port)
+}
+
+/**
+ * Install auto-start snippet into the primary shell profile.
+ * Idempotent — skips if already installed.
+ */
+export function installAutoStart(port: number = 3000): AutoStartResult {
+  const profiles = getShellProfiles()
+
+  if (profiles.length === 0) {
+    return {
+      success: false,
+      message: 'No supported shell profile found',
+      profilePath: '',
+    }
+  }
+
+  // Use the first (primary) profile
+  const profilePath = profiles[0]
+
+  // Already installed?
+  if (profileContainsSnippet(profilePath)) {
+    log(`Auto-start already installed in ${profilePath}`)
+    return {
+      success: true,
+      message: 'Auto-start already installed',
+      profilePath,
+    }
+  }
+
+  // Ensure parent directory exists
+  const dir = dirname(profilePath)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  // Read existing content or start fresh
+  const existing = existsSync(profilePath) ? readFileSync(profilePath, 'utf-8') : ''
+
+  // Append snippet with a blank line separator
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n\n' : '\n'
+  const snippet = getSnippetForProfile(profilePath, port)
+  writeFileSync(profilePath, existing + separator + snippet + '\n', 'utf-8')
+
+  log(`Auto-start installed in ${profilePath}`)
+  return {
+    success: true,
+    message: `Auto-start installed in ${profilePath}`,
+    profilePath,
+  }
+}
+
+/**
+ * Remove auto-start snippet from all known shell profiles.
+ * Removes everything between and including the marker comments.
+ */
+export function uninstallAutoStart(): AutoStartResult {
+  const profiles = getShellProfiles()
+  let removedFrom = ''
+
+  for (const profilePath of profiles) {
+    if (!existsSync(profilePath)) continue
+
+    const content = readFileSync(profilePath, 'utf-8')
+    if (!content.includes(START_MARKER)) continue
+
+    // Remove the snippet block (markers + everything between)
+    const startIdx = content.indexOf(START_MARKER)
+    const endIdx = content.indexOf(END_MARKER)
+
+    if (startIdx === -1 || endIdx === -1) continue
+
+    const endOfMarker = endIdx + END_MARKER.length
+    // Also remove trailing newline after end marker
+    const endWithNewline =
+      endOfMarker < content.length && content[endOfMarker] === '\n'
+        ? endOfMarker + 1
+        : endOfMarker
+
+    // Remove leading blank line if the snippet was appended with separator
+    let start = startIdx
+    if (start > 0 && content[start - 1] === '\n') {
+      start--
+      if (start > 0 && content[start - 1] === '\n') {
+        start--
+      }
+    }
+
+    const cleaned = content.slice(0, start) + content.slice(endWithNewline)
+    writeFileSync(profilePath, cleaned, 'utf-8')
+    removedFrom = profilePath
+    log(`Auto-start removed from ${profilePath}`)
+  }
+
+  if (!removedFrom) {
+    log('Auto-start was not installed in any profile')
+    return {
+      success: true,
+      message: 'Auto-start was not installed in any profile',
+      profilePath: '',
+    }
+  }
+
+  return {
+    success: true,
+    message: `Auto-start removed from ${removedFrom}`,
+    profilePath: removedFrom,
+  }
+}
+
+/**
+ * Check if auto-start is installed in any known shell profile.
+ */
+export function isAutoStartInstalled(): boolean {
+  const profiles = getShellProfiles()
+  return profiles.some((p) => profileContainsSnippet(p))
+}

package/src/cli/bin.ts

@@ -34,6 +34,7 @@ function printHelp() {
     ['uninstall', 'Remove MCP server from Claude Code'],
     ['update', 'Update package and refresh CLAUDE.md'],
     ['refresh', 'Kill all, update to latest, and setup everything'],
+    ['autostart', 'Manage auto-start on terminal open (install/uninstall/status)'],
     ['chroma', 'Manage ChromaDB server (start/stop/status)'],
     ['hooks', 'Manage passive learning hooks (install/uninstall/status)'],
     ['git-hook', 'Manage git post-commit hook (install/uninstall/status)'],
@@ -142,6 +143,12 @@ async function main() {
       break
     }
 
+    case 'autostart': {
+      const { runAutoStart } = await import('./commands/autostart')
+      await runAutoStart()
+      break
+    }
+
     case 'chroma': {
       const { runChroma } = await import('./commands/chroma')
       await runChroma()

package/src/cli/commands/autostart.ts

@@ -0,0 +1,90 @@
+/**
+ * claude-brain autostart — Manage auto-start on terminal open.
+ *
+ * Usage:
+ *   claude-brain autostart install    Install auto-start snippet in shell profile
+ *   claude-brain autostart uninstall  Remove auto-start snippet from shell profiles
+ *   claude-brain autostart status     Check if auto-start is installed
+ */
+
+import {
+  heading, successText, warningText, dimText, box,
+} from '@/cli/ui/index.js'
+import {
+  installAutoStart, uninstallAutoStart, isAutoStartInstalled, getShellProfiles,
+} from '@/cli/auto-start'
+
+export async function runAutoStart(): Promise<void> {
+  const subcommand = process.argv[3] || 'status'
+
+  switch (subcommand) {
+    case 'install': {
+      console.log()
+      console.log(heading('Auto-Start — Install'))
+      console.log()
+
+      const result = installAutoStart()
+      if (result.success) {
+        console.log(successText(`  ${result.message}`))
+        if (result.profilePath) {
+          console.log(dimText(`  Profile: ${result.profilePath}`))
+          console.log()
+          console.log(dimText('  Open a new terminal to activate.'))
+        }
+      } else {
+        console.log(warningText(`  ${result.message}`))
+      }
+      console.log()
+      break
+    }
+
+    case 'uninstall': {
+      console.log()
+      console.log(heading('Auto-Start — Uninstall'))
+      console.log()
+
+      const result = uninstallAutoStart()
+      console.log(successText(`  ${result.message}`))
+      console.log()
+      break
+    }
+
+    case 'status': {
+      console.log()
+      console.log(heading('Auto-Start — Status'))
+      console.log()
+
+      const installed = isAutoStartInstalled()
+      const profiles = getShellProfiles()
+
+      if (installed) {
+        console.log(successText('  Auto-start is installed'))
+      } else {
+        console.log(warningText('  Auto-start is not installed'))
+      }
+
+      console.log(dimText(`  Shell profiles checked: ${profiles.join(', ') || 'none found'}`))
+      console.log()
+
+      if (!installed) {
+        console.log(box([
+          dimText('Install with:'),
+          `  claude-brain autostart install`,
+        ].join('\n'), 'Tip'))
+        console.log()
+      }
+      break
+    }
+
+    default: {
+      console.log()
+      console.log(warningText(`Unknown subcommand: ${subcommand}`))
+      console.log()
+      console.log(dimText('Usage:'))
+      console.log(dimText('  claude-brain autostart install    Install auto-start'))
+      console.log(dimText('  claude-brain autostart uninstall  Remove auto-start'))
+      console.log(dimText('  claude-brain autostart status     Check status'))
+      console.log()
+    }
+  }
+}

package/src/cli/commands/install-mcp.ts

@@ -41,7 +41,7 @@ export async function runInstall() {
     } else {
       try {
         await withSpinner('Registering with Claude Code', async () => {
-          execSync('claude mcp add claude-brain -- claude-brain serve', {
+          execSync('claude mcp add claude-brain -s user -- claude-brain serve', {
             encoding: 'utf-8',
             stdio: ['pipe', 'pipe', 'pipe']
           })
@@ -59,7 +59,7 @@ export async function runInstall() {
             errorText('Failed to register automatically.'),
             '',
             dimText('Run manually:'),
-            `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
+            `  ${theme.bold('claude mcp add claude-brain -s user -- claude-brain serve')}`,
           ].join('\n'), 'Error'))
         }
       }
@@ -71,10 +71,10 @@ export async function runInstall() {
     console.log(box([
       `${theme.primary('Option 1:')} Install globally, then register`,
       `  ${theme.bold('bun install -g claude-brain')}`,
-      `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
+      `  ${theme.bold('claude mcp add claude-brain -s user -- claude-brain serve')}`,
       '',
       `${theme.primary('Option 2:')} Use bunx ${dimText('(zero-install)')}`,
-      `  ${theme.bold('claude mcp add claude-brain -- bunx claude-brain@latest')}`,
+      `  ${theme.bold('claude mcp add claude-brain -s user -- bunx claude-brain@latest')}`,
       '',
       `${theme.primary('Option 3:')} Add to Claude Code config manually`,
       dimText('  Add to your Claude Code MCP settings:'),

package/src/cli/commands/refresh.ts

@@ -128,7 +128,7 @@ function isMcpConfigured(): boolean {
 
 function registerMcp(): boolean {
   try {
-    execSync('claude mcp add claude-brain -- claude-brain serve', {
+    execSync('claude mcp add claude-brain -s user -- claude-brain serve', {
       encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10_000,
     })
     return true

package/src/cli/commands/serve.ts

@@ -41,6 +41,37 @@ export async function runServe() {
     console.error(`[claude-brain] Hook auto-install skipped: ${error instanceof Error ? error.message : 'unknown error'}`)
   }
 
+  // Auto-install shell auto-start if not already present (handles bun blocking postinstall)
+  try {
+    const { isAutoStartInstalled, installAutoStart } = await import('@/cli/auto-start')
+    if (!isAutoStartInstalled()) {
+      const result = installAutoStart()
+      if (result.success && result.profilePath) {
+        console.error(`[claude-brain] Auto-start installed in ${result.profilePath}`)
+      }
+    }
+  } catch (error) {
+    // Non-fatal — auto-start is a convenience feature
+  }
+
+  // Auto-install CLAUDE.md if not present (handles bun blocking postinstall)
+  try {
+    const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import('node:fs')
+    const { join, resolve, dirname } = await import('node:path')
+    const { homedir } = await import('node:os')
+    const { fileURLToPath } = await import('node:url')
+    const claudeMdDest = join(homedir(), '.claude', 'CLAUDE.md')
+    const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
+    const claudeMdSrc = join(pkgRoot, 'assets', 'CLAUDE.md')
+    if (existsSync(claudeMdSrc) && !existsSync(claudeMdDest)) {
+      mkdirSync(join(homedir(), '.claude'), { recursive: true })
+      writeFileSync(claudeMdDest, readFileSync(claudeMdSrc, 'utf-8'), 'utf-8')
+      console.error('[claude-brain] CLAUDE.md installed to ~/.claude/CLAUDE.md')
+    }
+  } catch {
+    // Non-fatal
+  }
+
   const config = await loadConfig()
 
   if (config.logLevel === 'debug' || config.logLevel === 'info') {
@@ -208,6 +239,44 @@ export async function runServe() {
     }
   }
 
+  // Phase 31: Auto-update checker
+  let autoUpdater: InstanceType<typeof import('@/server/auto-updater').AutoUpdater> | null = null
+  if (config.autoUpdate?.enabled !== false) {
+    try {
+      const { AutoUpdater } = await import('@/server/auto-updater')
+      autoUpdater = new AutoUpdater(
+        {
+          enabled: config.autoUpdate?.enabled ?? true,
+          checkIntervalHours: config.autoUpdate?.checkIntervalHours ?? 24,
+          autoRestart: config.autoUpdate?.autoRestart ?? true,
+        },
+        mainLogger
+      )
+
+      // Check for updates on startup (non-blocking)
+      autoUpdater.check().then(result => {
+        if (result.updateAvailable && result.latestVersion) {
+          mainLogger.info(
+            { current: result.currentVersion, latest: result.latestVersion },
+            'Update available! Run: claude-brain update'
+          )
+        }
+      }).catch(() => {})
+
+      // Schedule periodic checks
+      autoUpdater.schedulePeriodicCheck()
+
+      cleanup.register(async () => {
+        autoUpdater?.stopPeriodicCheck()
+        mainLogger.info('Auto-updater stopped')
+      })
+
+      mainLogger.info('Auto-updater initialized')
+    } catch (error) {
+      mainLogger.warn({ error }, 'Failed to initialize auto-updater')
+    }
+  }
+
   // Start HTTP server after MCP server is ready
   setTimeout(async () => {
     try {

package/src/cli/commands/uninstall-mcp.ts

@@ -14,12 +14,12 @@ export async function runUninstall() {
   try {
     await withSpinner('Removing Claude Brain from Claude Code', async () => {
       try {
-        execSync('claude mcp remove claude-brain', {
+        execSync('claude mcp remove claude-brain -s user', {
           encoding: 'utf-8',
           stdio: ['pipe', 'pipe', 'pipe'],
         })
       } catch {
-        // Falls back to scoped removal when registered in multiple scopes
+        // Falls back to local scope removal in case it was registered there
         execSync('claude mcp remove claude-brain -s local', {
           encoding: 'utf-8',
           stdio: ['pipe', 'pipe', 'pipe'],

package/src/config/schema.ts

@@ -346,6 +346,16 @@ export const ConfigSchema = z.object({
     enabled: z.boolean().default(true),
   }).default({} as any),
 
+  /** Phase 31: Auto-update configuration */
+  autoUpdate: z.object({
+    /** Enable automatic update checks */
+    enabled: z.boolean().default(true),
+    /** Hours between update checks */
+    checkIntervalHours: z.number().int().min(1).max(168).default(24),
+    /** Automatically restart server after update */
+    autoRestart: z.boolean().default(true),
+  }).default({} as any),
+
   /** Phase 30: Optional LLM compression for observations */
   compression: z.object({
     /** Enable LLM-based compression of long observations */

package/src/server/auto-updater.ts

@@ -0,0 +1,301 @@
+/**
+ * Auto-updater for claude-brain.
+ * Checks npm for new versions periodically, auto-updates with ghost process cleanup and fresh restart.
+ */
+
+import { execSync, spawn } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { homedir, platform } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PACKAGE_ROOT = resolve(__dirname, '..', '..')
+
+interface UpdateCheckResult {
+  currentVersion: string
+  latestVersion: string | null
+  updateAvailable: boolean
+  lastChecked: string
+}
+
+interface AutoUpdateConfig {
+  enabled: boolean
+  checkIntervalHours: number
+  autoRestart: boolean
+}
+
+const DEFAULT_CONFIG: AutoUpdateConfig = {
+  enabled: true,
+  checkIntervalHours: 24,
+  autoRestart: true,
+}
+
+const isWindows = platform() === 'win32'
+
+export class AutoUpdater {
+  private dataDir: string
+  private checkFile: string
+  private config: AutoUpdateConfig
+  private timer: ReturnType<typeof setInterval> | null = null
+  private logger: { info: (...args: any[]) => void; warn: (...args: any[]) => void; error: (...args: any[]) => void }
+
+  constructor(config?: Partial<AutoUpdateConfig>, logger?: any) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.dataDir = join(homedir(), '.claude-brain', 'data')
+    this.checkFile = join(this.dataDir, 'update-check.json')
+    this.logger = logger ?? {
+      info: (...args: any[]) => console.error('[auto-updater] INFO:', ...args),
+      warn: (...args: any[]) => console.error('[auto-updater] WARN:', ...args),
+      error: (...args: any[]) => console.error('[auto-updater] ERROR:', ...args),
+    }
+  }
+
+  /** Check npm registry for latest version */
+  async check(): Promise<UpdateCheckResult> {
+    const currentVersion = this.getCurrentVersion()
+
+    // Return cached result if checked recently
+    if (!this.shouldCheck()) {
+      try {
+        const cached = JSON.parse(readFileSync(this.checkFile, 'utf-8')) as UpdateCheckResult
+        return { ...cached, currentVersion }
+      } catch {
+        // Corrupted cache, proceed with fresh check
+      }
+    }
+
+    let latestVersion: string | null = null
+    try {
+      const result = execSync('npm view claude-brain version', {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 15_000,
+      })
+      latestVersion = result.trim()
+    } catch {
+      this.logger.warn('Failed to check npm registry for latest version')
+    }
+
+    const updateAvailable = latestVersion !== null && latestVersion !== currentVersion
+    const checkResult: UpdateCheckResult = {
+      currentVersion,
+      latestVersion,
+      updateAvailable,
+      lastChecked: new Date().toISOString(),
+    }
+
+    // Persist check result
+    try {
+      mkdirSync(this.dataDir, { recursive: true })
+      writeFileSync(this.checkFile, JSON.stringify(checkResult, null, 2), 'utf-8')
+    } catch (err) {
+      this.logger.warn('Failed to write update check file:', err)
+    }
+
+    if (updateAvailable) {
+      this.logger.info(`Update available: v${currentVersion} -> v${latestVersion}`)
+    }
+
+    return checkResult
+  }
+
+  /** Perform the update: kill ghosts -> update package -> restart */
+  async performUpdate(targetVersion: string): Promise<boolean> {
+    try {
+      this.logger.info(`Updating claude-brain to v${targetVersion}...`)
+
+      // Kill ghost processes
+      this.killGhostProcesses()
+
+      // Wait for ports to release
+      await this.sleep(2000)
+
+      // Try bun first, fallback to npm
+      try {
+        execSync('bun install -g claude-brain@latest', {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 120_000,
+        })
+        this.logger.info(`Updated to v${targetVersion} via bun`)
+      } catch {
+        try {
+          execSync('npm install -g claude-brain@latest', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 120_000,
+          })
+          this.logger.info(`Updated to v${targetVersion} via npm`)
+        } catch (err) {
+          this.logger.error('Install failed with both bun and npm:', err)
+          return false
+        }
+      }
+
+      if (this.config.autoRestart) {
+        this.restartServer()
+      }
+
+      return true
+    } catch (err) {
+      this.logger.error('Update failed:', err)
+      return false
+    }
+  }
+
+  /** Schedule periodic background checks */
+  schedulePeriodicCheck(): void {
+    if (!this.config.enabled) return
+    if (this.timer) return
+
+    const intervalMs = this.config.checkIntervalHours * 3600 * 1000
+
+    this.timer = setInterval(async () => {
+      try {
+        const result = await this.check()
+        if (result.updateAvailable && result.latestVersion && this.config.enabled) {
+          await this.performUpdate(result.latestVersion)
+        }
+      } catch (err) {
+        this.logger.error('Periodic update check failed:', err)
+      }
+    }, intervalMs)
+
+    // Don't keep the process alive just for the update timer
+    if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+      this.timer.unref()
+    }
+
+    this.logger.info(`Scheduled update checks every ${this.config.checkIntervalHours}h`)
+  }
+
+  /** Stop periodic checks */
+  stopPeriodicCheck(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+  }
+
+  /** Check if enough time has passed since last check */
+  private shouldCheck(): boolean {
+    if (!existsSync(this.checkFile)) return true
+
+    try {
+      const data = JSON.parse(readFileSync(this.checkFile, 'utf-8')) as UpdateCheckResult
+      if (!data.lastChecked) return true
+
+      const lastChecked = new Date(data.lastChecked).getTime()
+      const intervalMs = this.config.checkIntervalHours * 3600 * 1000
+      return Date.now() - lastChecked >= intervalMs
+    } catch {
+      return true
+    }
+  }
+
+  /** Kill all ghost claude-brain processes */
+  private killGhostProcesses(): void {
+    const myPid = process.pid
+
+    // Kill by pattern
+    try {
+      if (isWindows) {
+        const result = execSync(
+          `wmic process where "commandline like '%claude-brain%' and processid != ${myPid}" get processid /format:list`,
+          { encoding: 'utf-8', stdio: 'pipe', timeout: 5000 }
+        )
+        const pids = result.match(/ProcessId=(\d+)/g)?.map(m => m.split('=')[1]) || []
+        for (const pid of pids) {
+          try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe', timeout: 5000 }) } catch {}
+        }
+      } else {
+        const result = execSync(`pgrep -f "claude-brain"`, {
+          encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
+        })
+        const pids = result.trim().split('\n').filter(p => p && Number(p) !== myPid)
+        for (const pid of pids) {
+          try { process.kill(Number(pid), 'SIGKILL') } catch {}
+        }
+      }
+    } catch {
+      // No matching processes — that's fine
+    }
+
+    // Kill by port 3000
+    try {
+      if (isWindows) {
+        const result = execSync(`netstat -ano | findstr :3000 | findstr LISTENING`, {
+          encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
+        })
+        const pids = new Set(
+          result.split('\n')
+            .map(line => line.trim().split(/\s+/).pop())
+            .filter(p => p && Number(p) !== myPid)
+        )
+        for (const pid of pids) {
+          try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe', timeout: 5000 }) } catch {}
+        }
+      } else {
+        const raw = execSync(`lsof -ti :3000`, {
+          encoding: 'utf-8', stdio: 'pipe', timeout: 5000,
+        }).trim()
+        if (raw) {
+          const pids = raw.split('\n').filter(p => p && Number(p) !== myPid)
+          for (const pid of pids) {
+            try { process.kill(Number(pid), 'SIGKILL') } catch {}
+          }
+        }
+      }
+    } catch {
+      // No process on port — that's fine
+    }
+
+    // Clean up stale PID files
+    const pidPath = join(this.dataDir, 'server.pid')
+    if (existsSync(pidPath)) {
+      try {
+        const pid = parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
+        if (!isNaN(pid) && pid !== myPid) {
+          try { process.kill(pid, 0) } catch {
+            // Process not running, remove stale PID file
+            try { unlinkSync(pidPath) } catch {}
+          }
+        }
+      } catch {}
+    }
+  }
+
+  /** Spawn a fresh server instance and exit current */
+  private restartServer(): void {
+    this.logger.info('Restarting server with updated version...')
+
+    const child = spawn('claude-brain', ['serve'], {
+      detached: true,
+      stdio: 'ignore',
+    })
+
+    child.unref()
+
+    this.logger.info(`Spawned new server process (PID: ${child.pid}). Exiting current process.`)
+    process.exit(0)
+  }
+
+  /** Get current installed version from package.json */
+  private getCurrentVersion(): string {
+    try {
+      // Use the version from the package that's actually running
+      const pkgPath = join(PACKAGE_ROOT, 'package.json')
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        return pkg.version || 'unknown'
+      }
+    } catch {}
+    return 'unknown'
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}