claude-mem/docs/reports/2026-01-05--issue-555-windows-hooks-ipc-false.md

Issue #555 Analysis: Windows Hooks Not Executing - hasIpc Always False

Date: 2026-01-05 Version Analyzed: 8.5.9 Claude Code Version: 2.0.76 Platform: Windows 11 (Build 26100), Git Bash (MINGW64) Status: INVESTIGATION COMPLETE - Root cause identified

Issue Summary

On Windows 11 with Git Bash, Claude-mem plugin hooks are not executing at all. While the worker service starts successfully and responds to health checks, no observations are being saved and no hook-related logs appear.

Reported Symptoms

// /api/health
{
  "status": "ok",
  "build": "TEST-008-wrapper-ipc",
  "managed": false,
  "hasIpc": false,
  "platform": "win32",
  "pid": 3596,
  "initialized": true,
  "mcpReady": true
}

// /api/stats
{
  "observations": 0,
  "sessions": 1
}

Key Observations

1. Worker starts and responds correctly to HTTP requests
2. hasIpc is false (this is expected behavior, not a bug)
3. observations remains at 0 - no data being captured
4. No [HOOK] entries in worker logs - hooks never execute
5. This differs from issue #517 which was about PowerShell escaping

Root Cause Analysis

Primary Cause: Hook Commands Not Executing

The hooks defined in plugin/hooks/hooks.json are never being invoked by Claude Code on Windows.

Understanding hasIpc

The hasIpc field is a red herring and is working as intended:

// src/services/server/Server.ts:152
hasIpc: typeof process.send === 'function'

This checks if the worker process was spawned with an IPC channel (via fork() or spawn() with stdio: 'ipc'). Plugin hooks execute as independent command-line processes, NOT as forked child processes with IPC channels. Therefore, hasIpc: false is the expected, normal behavior for all hook executions.

Actual Problem: Hook Command Execution Failure

The hooks.json uses Unix-style environment variable syntax:

{
  "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start"
}

On Windows, this fails because:

1. Shell Interpreter Mismatch: Claude Code on Windows likely uses cmd.exe or PowerShell to execute hook commands, not Git Bash. The ${VARIABLE} syntax only works in Bash; cmd.exe uses %VARIABLE%.

2. PATH Environment Differences: The user runs Claude in Git Bash where bun and node are in PATH. However, Claude Code executes hooks in its own shell context (likely cmd.exe), which may not inherit Git Bash's PATH configuration.

3. CLAUDE_PLUGIN_ROOT Resolution: If Claude Code doesn't properly set or expand CLAUDE_PLUGIN_ROOT before executing the command, the entire path becomes invalid.

Code Investigation Findings

Affected Files

File	Purpose	Issue
plugin/hooks/hooks.json	Hook command definitions	Uses ${CLAUDE_PLUGIN_ROOT} Unix syntax
plugin/scripts/smart-install.js	Dependency installer	Executed via hooks.json, never runs on Windows
plugin/scripts/worker-service.cjs	Worker CLI	Executed via hooks.json, never runs on Windows
plugin/scripts/*.js	Hook scripts	None execute because hooks.json commands fail

hooks.json Analysis

Current hooks.json commands:

{
  "SessionStart": [{
    "hooks": [
      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/smart-install.js\"" },
      { "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start" },
      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js\"" }
    ]
  }],
  "PostToolUse": [{
    "hooks": [
      { "command": "bun \"${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs\" start" },
      { "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js\"" }
    ]
  }]
}

Problems identified:

1. ${CLAUDE_PLUGIN_ROOT} - Unix variable expansion, fails in cmd.exe
2. bun command - May not be in system PATH on Windows
3. node command - May not be in system PATH accessible to Claude Code

Worker hasIpc Usage

The hasIpc field is used only for admin endpoint IPC messaging, which is a separate concern from hook execution:

// src/services/server/Server.ts:209-216
const isWindowsManaged = process.platform === 'win32' &&
  process.env.CLAUDE_MEM_MANAGED === 'true' &&
  process.send;

if (isWindowsManaged) {
  process.send!({ type: 'restart' });
}

This IPC mechanism is for managed process scenarios and is unrelated to why hooks aren't executing.

Relationship to Issue #517

Aspect	Issue #517	Issue #555
Problem	PowerShell $_ variable misinterpreted by Bash	Hooks not executing at all
Location	ProcessManager.ts (worker internals)	hooks.json execution by Claude Code
Fix Applied	Replaced PowerShell with WMIC	N/A (new issue)
Scope	Worker process management	Claude Code hook invocation

Issue #517 fixed internal worker operations (orphaned process cleanup). Issue #555 is a completely different layer - it's about Claude Code's plugin system failing to invoke hooks on Windows.

Proposed Fix

Option 1: Cross-Platform Wrapper Script (Recommended)

Create a platform-aware wrapper that handles path resolution:

// plugin/scripts/hook-runner.js
#!/usr/bin/env node
const path = require('path');
const { spawn } = require('child_process');

// Resolve CLAUDE_PLUGIN_ROOT or compute from script location
const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ||
  path.dirname(__dirname);

const hookScript = process.argv[2];
const hookPath = path.join(pluginRoot, 'scripts', hookScript);

// Execute the actual hook
require(hookPath);

Update hooks.json to use relative paths:

{
  "command": "node ./scripts/hook-runner.js context-hook.js"
}

Option 2: Windows-Specific hooks.json

Create a Windows-compatible version using %CLAUDE_PLUGIN_ROOT% syntax:

{
  "command": "node \"%CLAUDE_PLUGIN_ROOT%\\scripts\\smart-install.js\""
}

Drawback: Requires maintaining two hooks.json versions or using conditional logic.

Option 3: Use Absolute Paths

Generate hooks.json at install time with resolved absolute paths:

{
  "command": "node \"C:\\Users\\username\\.claude\\plugins\\marketplaces\\thedotmack\\plugin\\scripts\\smart-install.js\""
}

Drawback: Less portable, requires install-time generation.

Option 4: Ensure bun/node in System PATH

Add installation validation to ensure bun and node are in the system-wide PATH, not just Git Bash's PATH:

# In smart-install.js for Windows
if (IS_WINDOWS) {
  // Add to system PATH if not present
  // Or use absolute paths to node/bun executables
}

Debugging Steps for Users

1. Verify plugin registration:

   claude /status
   

2. Check plugin installation:

   dir $env:USERPROFILE\.claude\plugins\marketplaces\thedotmack\plugin\hooks
   

3. Test environment variable:

   $env:CLAUDE_PLUGIN_ROOT = "$env:USERPROFILE\.claude\plugins\marketplaces\thedotmack\plugin"
   node "$env:CLAUDE_PLUGIN_ROOT\scripts\smart-install.js"
   

4. Check if node/bun are in system PATH:

   where.exe node
   where.exe bun
   

5. Enable Claude Code debug logging:

   • Check Claude Code settings for debug/verbose mode
   • Look for hook execution errors in logs

Impact Assessment

• Severity: High - Complete loss of memory functionality on Windows
• Scope: All Windows users, especially those using Git Bash
• Workaround: None currently - hooks must execute for memory to work
• Affected Versions: Likely affects 8.5.x on Windows with Claude Code 2.0.76+

Recommended Actions

1. Immediate: Document the issue and potential workarounds
2. Short-term: Implement Option 1 (cross-platform wrapper script)
3. Long-term: Request clarification from Anthropic on Windows hook execution behavior
4. Testing: Add Windows CI/CD testing for hook execution

Files to Modify

1. plugin/hooks/hooks.json - Update command syntax
2. plugin/scripts/hook-runner.js - New cross-platform wrapper (create)
3. plugin/scripts/smart-install.js - Add PATH validation for Windows
4. docs/public/troubleshooting.mdx - Document Windows hook issues

Appendix: Technical Details

Environment Variable Expansion by Shell

Shell	Syntax	Works in hooks.json
Bash	${VAR} or $VAR	Yes (if Bash executes)
cmd.exe	%VAR%	Yes (if cmd executes)
PowerShell	$env:VAR	Yes (if PS executes)

Claude Code Hook Execution Flow

1. Claude Code loads hooks.json from plugin directory
2. On hook event (SessionStart, PostToolUse, etc.), executes defined commands
3. Commands are executed via system shell (platform-dependent)
4. Hook process receives JSON via stdin, outputs response to stdout
5. Claude Code processes hook output

The failure occurs at step 3 when the shell cannot resolve the command or environment variables.