Windows Terminal Popup Regression

[xingyu42]

---

Issue Template: Windows Terminal Popup Regression

Title: [BUG] Blank terminal windows pop up on Windows during hook execution (ProcessManager regression)

Labels: bug, platform-windows, needs-triage

---

Bug Description
On Windows systems, blank console/terminal windows appear and disappear rapidly whenever a hook is triggered (e.g., during SessionStart, UserPromptSubmit, or PostToolUse).
This causes visual flickering and interrupts the user workflow.

Root Cause
The src/services/infrastructure/ProcessManager.ts was using the native Node.js/Bun spawn() method with the following configuration:

1 spawn(process.execPath, [scriptPath, '--daemon'], {
2 detached: true,
3 windowsHide: true, // <--- This fails on Windows when detached is true
4 // ...
5 });
There is a known limitation in Node.js (and Bun) where windowsHide: true does not work as expected when detached: true is used, especially when spawning shell-like processes or wrappers. Reference: Node.js Issue #21825 (nodejs/node#21825).

A previous fix existed in the legacy worker-cli.ts but was lost during the modular refactor that introduced the current ProcessManager.ts.

Steps to Reproduce

1. Use Claude Code on Windows 10/11.
2. Start a new session or submit a prompt.
3. Observe multiple blank terminal windows flashing on the taskbar and screen.

Expected Behavior
The worker daemon should start silently in the background without any visible terminal windows popping up.

Proposed Fix / Implemented Solution
The fix involves wrapping the process launch in a PowerShell command using -WindowStyle Hidden, which is the only reliable way to hide detached processes on Windows:

1 // Windows-specific launch in ProcessManager.ts
2 const psCommand = Start-Process -FilePath '${escapedExecPath}' -ArgumentList '${escapedArgs}' -WindowStyle Hidden -PassThru | Select-Object -ExpandProperty Id;
3
4 spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCommand], {
5 windowsHide: true,
6 stdio: 'pipe'
7 });

Key Improvements in the Fix:

1. Reliable Hiding: Uses PowerShell's native window management.
2. Environment Parity: Properly passes extraEnv and CLAUDE_MEM_WORKER_PORT through the PowerShell scope.
3. Safety: Includes escapePowerShellString to prevent path injection.
4. Efficiency: Adds -NoProfile and -NonInteractive to PowerShell to ensure fast execution and clean output.

Environment

• OS: Windows10 (win32)
• Claude-mem version: 9.0.4+
• Platform: Node.js / Bun

[thedotmack]

@claude Explain what detach=true is used for in this case

[claude]

Claude finished @thedotmack's task in 35s —— View job

---

Todo List

• Read ProcessManager.ts to understand the implementation
• Explain the purpose of detached: true in this context
• Connect the explanation to the bug and the fix

---

What detached: true Does

In this case, detached: true is used to create a daemon process that runs independently of its parent process. Here's why that's critical for claude-mem's worker service:

The Purpose

When you spawn a child process with detached: true (line 272 in ProcessManager.ts:spawnDaemon), it:

1. Creates a new process group - The child process becomes the leader of its own process group instead of inheriting the parent's
2. Survives parent termination - When the parent process (the hook script) exits, the child (worker daemon) continues running
3. Enables true background operation - Combined with child.unref() (line 286), this allows the parent to exit without waiting for the child

Why It's Needed Here

Claude-mem's architecture requires the worker service to run as a persistent background daemon:

• Hooks (SessionStart, UserPromptSubmit, etc.) are short-lived processes that spawn the worker
• The worker must outlive these hooks to handle requests across multiple Claude Code sessions
• Without detached: true, killing the hook would also kill the worker, breaking the persistence model

The Windows Problem

The bug occurs because on Windows, detached: true and windowsHide: true conflict:

// This doesn't work reliably on Windows (line 271-274)
spawn(process.execPath, [scriptPath, '--daemon'], {
  detached: true,      // ← Creates independent process
  windowsHide: true,   // ← Tries to hide window... but fails when detached
  // ...
});

When a process is detached on Windows, the Node.js/Bun runtime can't reliably control its window state. This is a known Node.js limitation - the windowsHide flag is ignored, and Windows creates a visible console window by default.

The Solution

The fix works around this by using PowerShell's native process creation which has its own window management:

Start-Process -FilePath 'bun' -ArgumentList 'script.js --daemon' -WindowStyle Hidden

PowerShell's -WindowStyle Hidden operates at the OS level (through Windows API calls) rather than trying to set flags on an already-detached process, which is why it works reliably.

---

[thedotmack]

@claude what process is being spawned? Scour the codebase for all evidence of spawning pattern.

Newest version should have only hooks.json pointing to cli commands and zero hook files and we only use smart-install.js — what is being spawned by our process? If it’s chroma then it probably is not correctly using the MCP package for execution. Nothing else really should be spawning ever anywhere at this point in the codebase… unless I’m missing something. Please report back your findings.

[claude]

Claude finished @thedotmack's task in 2m 59s —— View job

---

Investigation: Process Spawning in Claude-Mem

Todo List

• Search codebase for all spawn/exec/fork patterns
• Review hooks.json configuration
• Check for hook file existence
• Examine smart-install.js
• Investigate Chroma integration
• Review MCP package usage
• Compile and report findings

---

Findings: Two Sources of Windows Terminal Popups

1. Current Hook Architecture ✅

The newest version DOES use the correct architecture as expected:

• plugin/hooks/hooks.json exists with hook definitions pointing to CLI commands
• No .js hook files in plugin/hooks/ directory (only hooks.json and docs)
• All hooks call smart-install.js and worker-service.cjs via command-line

This matches your expectation perfectly.

---

2. The Two Process Spawning Culprits

A. Worker Daemon Spawning - src/services/infrastructure/ProcessManager.ts:266-288

WHERE IT'S USED: Called from worker-service.ts during start command (lines 585, 693, 735)

export function spawnDaemon(scriptPath: string, port: number, extraEnv: Record<string, string> = {}): number | undefined {
  const child = spawn(process.execPath, [scriptPath, '--daemon'], {
    detached: true,
    stdio: 'ignore',
    windowsHide: true,  // ⚠️ DOESN'T WORK with detached: true on Windows
    env: { ...process.env, CLAUDE_MEM_WORKER_PORT: String(port), ...extraEnv }
  });
  
  if (child.pid === undefined) return undefined;
  child.unref();
  return child.pid;
}

ISSUE: This is the exact pattern described in the bug report:

• detached: true + windowsHide: true = Windows terminal popup
• Called during: start command, restart command, and interactive setup
• This spawns the worker daemon itself (the Express API server)

WHY IT HAPPENS:

• Every hook calls bun worker-service.cjs start first (see hooks.json lines 15, 36, 53, 69)
• start checks if worker is running; if not, calls spawnDaemon()
• On Windows, the windowsHide flag is ignored when detached: true, creating visible console windows

TRIGGER FREQUENCY: Every single hook execution that needs to start the worker (SessionStart, UserPromptSubmit, PostToolUse, Stop)

---

B. Chroma MCP Server Spawning - src/services/sync/ChromaSync.ts:106-124

WHERE IT'S USED: Whenever vector search is accessed (backfill, search, sync operations)

const transportOptions: any = {
  command: 'uvx',
  args: ['--python', pythonVersion, 'chroma-mcp', '--client-type', 'persistent', '--data-dir', this.VECTOR_DB_DIR],
  stderr: 'ignore'
};

// CRITICAL: On Windows, try to hide console window to prevent PowerShell popups
// Note: windowsHide may not be supported by MCP SDK's StdioClientTransport
if (isWindows) {
  transportOptions.windowsHide = true;  // ⚠️ MAY NOT BE SUPPORTED BY MCP SDK
  logger.debug('CHROMA_SYNC', 'Windows detected, attempting to hide console window');
}

this.transport = new StdioClientTransport(transportOptions);

ISSUE:

• Passes windowsHide: true to MCP SDK's StdioClientTransport
• The code comment explicitly admits uncertainty about MCP SDK support
• MCP SDK internally spawns uvx → Python → Chroma process
• This could create visible console windows if the option isn't supported

TRIGGER FREQUENCY: During vector search operations (less frequent than worker spawning)

---

Root Cause Analysis

You're partially missing something: The worker daemon IS still being spawned, just not by legacy hook files.

Current Flow:

1. Hook triggers (e.g., SessionStart) → bun worker-service.cjs start
2. start command checks if worker is running via health check
3. If not running → calls ProcessManager.spawnDaemon(__filename, port)
4. On Windows: spawn() with detached: true ignores windowsHide: true → popup appears

Files Involved:

• plugin/hooks/hooks.json - Defines hooks (correct architecture) ✅
• plugin/scripts/worker-service.cjs - CLI wrapper (built from src/services/worker-service.ts)
• src/services/worker-service.ts - Calls spawnDaemon() ⚠️
• src/services/infrastructure/ProcessManager.ts - Contains buggy spawnDaemon() ⚠️
• src/services/sync/ChromaSync.ts - Spawns Chroma MCP process ⚠️

---

Recommended Fix

Apply the PowerShell wrapper solution from the issue description to both spawning locations:

1. ProcessManager.spawnDaemon() - Fix worker daemon spawning (high priority - affects every hook)
2. ChromaSync.ts - Either:
   • Verify MCP SDK supports windowsHide natively (check SDK source)
   • Or apply similar PowerShell wrapper if not supported

The issue description already provides the exact implementation for #1. Would you like me to implement both fixes?

---

[deeppaz]

@claude yes, please fix this annoying issue :D

[Lokieys]

Proposed Fix for ProcessManager.spawnDaemon()

Confirmed root cause: windowsHide: true does not work with detached: true in Node.js spawn().
Reference: nodejs/node#21825

Fix

Replace spawn() with PowerShell Start-Process -WindowStyle Hidden on Windows in src/services/infrastructure/ProcessManager.ts:

export function spawnDaemon(
  scriptPath: string,
  port: number,
  extraEnv: Record<string, string> = {}
): number | undefined {
  const isWindows = process.platform === "win32";

  const envVars = {
    ...process.env,
    CLAUDE_MEM_WORKER_PORT: String(port),
    ...extraEnv
  };

  if (isWindows) {
    // Windows: Use PowerShell Start-Process with -WindowStyle Hidden
    // windowsHide does NOT work with detached: true
    try {
      const envPairs = Object.entries(extraEnv)
        .map(([k, v]) => `$env:${k}='${v}'`)
        .join("; ");
      const envSetup = envPairs ? `${envPairs}; ` : "";

      const psCommand = `${envSetup}$env:CLAUDE_MEM_WORKER_PORT='${port}'; Start-Process -FilePath '${process.execPath}' -ArgumentList '"${scriptPath}"', '--daemon' -WindowStyle Hidden -PassThru | Select-Object -ExpandProperty Id`;

      const result = execSync(`powershell -NoProfile -NonInteractive -Command "${psCommand}"`, {
        timeout: HOOK_TIMEOUTS.POWERSHELL_COMMAND,
        windowsHide: true,
        env: envVars
      });

      const pid = parseInt(result.toString().trim(), 10);
      if (\!isNaN(pid) && pid > 0) {
        logger.info("SYSTEM", "Spawned daemon via PowerShell (hidden)", { pid, port });
        return pid;
      }
      return undefined;
    } catch (error) {
      logger.error("SYSTEM", "Failed to spawn daemon via PowerShell", { scriptPath, port }, error as Error);
      return undefined;
    }
  } else {
    // Unix: standard spawn
    const child = spawn(process.execPath, [scriptPath, "--daemon"], {
      detached: true,
      stdio: "ignore",
      env: envVars
    });
    if (child.pid === undefined) return undefined;
    child.unref();
    return child.pid;
  }
}

Secondary Issue

ChromaSync.ts line 120 passes windowsHide to MCP SDK's StdioClientTransport - this may not be supported by the SDK and could need a similar PowerShell wrapper.

Testing

Tested wrapper scripts locally on Windows 11 - PowerShell -WindowStyle Hidden properly hides windows where windowsHide: true with detached: true does not.

[thedotmack]

thanks @Lokieys I think we are getting closer!

@claude consider and research a fix where we NEVER SPAWN ANYTHING and we actually straight up don't use that pattern anymore

The mcp sdk used properly should not cause windows popup issues ever, and more wrappers makes the problem worse.

we don't need to spawn the damn worker with the worker! I am pretty sure we check for port conflicts and it should just not run the process if the port is in use, literally first thing first check.

We don't need anything fancy, the more you add to it, the more you abstract it, the worse it gets. The entire pattern is nonsense when you're hitting a CLI command, it's just not built correctly.

[claude]

Claude finished @thedotmack's task in 2m 32s —— View job

---

Todo List

• Read and understand current worker lifecycle and spawning pattern
• Analyze why spawning is happening (trace hook → CLI → spawn flow)
• Design architecture that eliminates all spawning
• Verify MCP SDK handles windowsHide internally
• Implement the simplified solution
• Test and verify changes

The Problem (You're Absolutely Right!)

Current Architecture (overcomplicated):

Hook → bun worker-service.cjs start
  ↓
  Checks if worker is running
  ↓
  If not running → spawn(bun, [worker-service.cjs, --daemon])
    ↓
    WINDOWS BUG: detached:true + windowsHide:true = POPUP ❌

Why this is nonsense:

1. Every hook calls start command
2. start command spawns a daemon of itself 🤦
3. The daemon is just an HTTP server - it doesn't need this circular complexity
4. Port-based detection should be ENOUGH

The Solution: Eliminate All Spawning from worker-service.ts

Implementation Plan:

1. Remove spawnDaemon() calls from worker-service.ts

Remove or modify these lines:

• Line 585: Interactive setup spawning
• Line 693: start command spawning
• Line 735: restart command spawning

2. Change start command to check-only mode

case 'start': {
  // Just verify worker is running - don't start it
  if (await waitForHealth(port, 1000)) {
    const versionCheck = await checkVersionMatch(port);
    if (!versionCheck.matches) {
      logger.info('SYSTEM', 'Worker version mismatch - needs restart', {
        pluginVersion: versionCheck.pluginVersion,
        workerVersion: versionCheck.workerVersion
      });
      exitWithStatus('error', 'Worker version mismatch - restart worker manually');
    } else {
      logger.info('SYSTEM', 'Worker already running and healthy');
      exitWithStatus('ready');
    }
  }

  const portInUse = await isPortInUse(port);
  if (portInUse) {
    logger.error('SYSTEM', 'Port in use but worker not responding');
    exitWithStatus('error', 'Port in use but worker not responding');
  }

  // NOT RUNNING - Don't spawn, just guide user
  logger.error('SYSTEM', 'Worker not running');
  exitWithStatus('error', 'Worker not running. Start manually with: bun worker-service.cjs --daemon');
}

3. Keep --daemon mode as the ONLY entry point

The --daemon case (line 792-802) stays - this is the actual server. Users run this directly:

# User starts worker ONCE
bun ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/worker-service.cjs --daemon

# OR in background with nohup (cross-platform)
nohup bun worker-service.cjs --daemon > /dev/null 2>&1 &

4. Update smart-install.js to start worker directly (optional)

Instead of calling bun worker-service.cjs start (which would spawn), smart-install can:

• Check if worker is running
• If not, show message: "Worker not running. Start with: bun worker-service.cjs --daemon"
• OR optionally spawn it ONCE during first install (with proper error handling)

5. For Chroma MCP - keep as-is

The Chroma spawning is different and correct:

• It spawns a subprocess (uvx chroma-mcp), not itself
• MCP SDK's StdioClientTransport likely handles windowsHide internally via Node.js spawn
• If MCP SDK doesn't support it, that's an SDK limitation - we can't fix it without wrapping

Note: The comment on line 118 says windowsHide may not be supported - this suggests it was already tried and didn't work. If popups still occur from Chroma, we'd need to:

1. Check if MCP SDK version >1.25.1 supports it
2. File an issue with MCP SDK project
3. OR wrap the MCP transport with PowerShell (but that defeats the purpose)

Benefits of NO SPAWNING Architecture

✅ No Windows popups - no spawning from worker = no windows
✅ Simpler logic - hooks don't manage processes
✅ Clearer responsibility - user controls worker lifecycle explicitly
✅ Easier debugging - worker runs as foreground process or user-managed daemon
✅ No circular spawning - worker doesn't spawn itself
✅ Process managers work - systemd, PM2, Docker can manage the worker properly

Migration Path

1. Immediate (v9.0.5): Remove spawning from start command
2. Documentation: Update install docs to show manual worker start
3. Future (v9.1.0): Add systemd/launchd service files for auto-start on boot
4. CI/CD: Update GitHub Actions to start worker manually in tests

Ready to implement?

This will:

1. Fix the Windows popup bug completely
2. Simplify the architecture dramatically
3. Require users to start worker manually (one-time setup)

Want me to proceed with this implementation?

---

[mrdornellesf]

Adding more details from my experience:

Environment:

Windows 11 64-bit
Claude Code VSCode Extension
claude-mem 9.0.0 (marketplace version)
Python 3.13.1
uv 0.5.18
The marketplace is still serving version 9.0.0, not 9.0.2. Ran claude plugin update claude-mem@thedotmack and got "already at the latest version (9.0.0)". Tried uninstall/reinstall, same result.

Also, setting CLAUDE_MEM_CHROMA_ENABLED: false in ~/.claude-mem/settings.json does NOT disable Chroma. The PowerShell windows still pop up and searches still try to connect to Chroma MCP server, resulting in timeouts and crashes.

Logs show:

[ERROR] Worker API error (500): {"error":"Chroma connection failed: MCP error -32001: Request timed out"}
Even with the flag set to false.

Two issues here:

Marketplace needs to be updated to 9.0.2+
CLAUDE_MEM_CHROMA_ENABLED config flag is being ignored
Had to disable the plugin entirely to continue working

[xingyu42]

Adding more details from my experience:

Environment:

Windows 11 64-bit Claude Code VSCode Extension claude-mem 9.0.0 (marketplace version) Python 3.13.1 uv 0.5.18 The marketplace is still serving version 9.0.0, not 9.0.2. Ran claude plugin update claude-mem@thedotmack and got "already at the latest version (9.0.0)". Tried uninstall/reinstall, same result.

Also, setting CLAUDE_MEM_CHROMA_ENABLED: false in ~/.claude-mem/settings.json does NOT disable Chroma. The PowerShell windows still pop up and searches still try to connect to Chroma MCP server, resulting in timeouts and crashes.

Logs show:

[ERROR] Worker API error (500): {"error":"Chroma connection failed: MCP error -32001: Request timed out"} Even with the flag set to false.

Two issues here:

Marketplace needs to be updated to 9.0.2+ CLAUDE_MEM_CHROMA_ENABLED config flag is being ignored Had to disable the plugin entirely to continue working

Check ./claude/plugin/ for remnants when uninstalling.