Windows: Installer completes but doesn't populate hooks array in settings.json

[ProgenyAlpha]

cc-sessions Version

0.3.6

Installation Method

npm/npx (JavaScript)

Operating System

Windows 10

Shell/Terminal

PowerShell / Git Bash

IDE/Environment

Terminal/CLI only

Bug Description

After installing cc-sessions on Windows via npx cc-sessions, the installation appears to complete successfully (creates sessions/ directory, config files, etc.), but the hooks configuration in ~/.claude/settings.json remains empty, making all hook-based functionality non-operational.

Current state of hooks in settings.json:

"hooks": {
  "UserPromptSubmit": [],
  "PreToolUse": [],
  "PostToolUse": [],
  "SessionStart": []
}

Expected state:
Hooks should be populated with node commands using %CLAUDE_PROJECT_DIR% syntax (as defined in installer source code lines 1781-1788).

Impact:

• Mode switching via trigger phrases doesn't work
• DAIC enforcement non-functional
• All protocol triggers fail
• Essentially makes cc-sessions non-operational

Verification

Hook scripts work correctly when executed manually:

cd C:\Users\username
echo '{"hook_event_name":"UserPromptSubmit","prompt":"yert","cwd":"C:\\Users\\username","session_id":"test"}' | node sessions/hooks/user_messages.js

Returns valid JSON output with implementation mode activation context. This confirms the hook scripts themselves are correct.

Installation artifacts created successfully:

• ✅ sessions/ directory with all subdirectories
• ✅ sessions/hooks/ with all hook scripts (user_messages.js, sessions_enforce.js, etc.)
• ✅ sessions-config.json and sessions-state.json
• ✅ CLAUDE.md modified with @sessions/CLAUDE.sessions.md reference
• ✅ .claude/settings.json modified (timestamp shows installer touched it)
• ❌ Hooks array in settings.json remains empty

Steps to Reproduce

1. Install cc-sessions on Windows: npx cc-sessions@latest
2. Complete installation wizard (select kickstart mode, configure preferences)
3. Installation reports success
4. Check ~/.claude/settings.json or .claude/settings.json
5. Observe that hooks object has empty arrays
6. Try using trigger phrases in Claude Code - nothing happens
7. Manually test hook: echo '{"prompt":"test"}' | node sessions/hooks/user_messages.js - works correctly

Expected Behavior

The installer's configure_settings() function should populate the hooks arrays with commands like:

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\user_messages.js\""
      }
    ]
  }
]

Possible Root Causes

Based on review of installer source code (cc_sessions/install.js lines 1776-1813):

1. findHookInSettings() logic issue: May incorrectly detect existing hooks and skip writing
2. Windows path handling: Possible issue with backslash escaping during JSON serialization
3. File write timing: Settings file may be written before hooks are fully prepared
4. Permissions/file locking: Windows-specific file access issue during installation

Related Issues

Similar reports suggest this may be a broader Windows compatibility issue:

• Sessions fails when installed in a directory path with a space #82 - Sessions fails with spaces in directory path
• Failed Kickstart Locks Up CC #79 - Failed kickstart locks up CC (Windows 11)
• After installing and then restarting claude code, I see this error mesage: #6 - Path expansion issues on non-Unix systems

Workaround

Manually add hooks to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\user_messages.js\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|Task|Bash|TodoWrite|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\sessions_enforce.js\""
          }
        ]
      },
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\subagent_hooks.js\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\post_tool_use.js\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|clear",
        "hooks": [
          {
            "type": "command",
            "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\kickstart_session_start.js\""
          }
        ]
      }
    ]
  }
}

After manually adding this configuration and restarting Claude Code, all functionality works correctly.

Additional Context

• Node version: (output of node --version)
• NPM version: (output of npm --version)
• Installation completed without errors
• No error messages during or after installation
• sessions-config.json shows "os": "linux" (should probably be "windows")

Suggestion

The installer should:

1. Verify hooks were written successfully after installation
2. Print the hooks configuration or confirmation that hooks were registered
3. Provide troubleshooting instructions if hooks fail to register
4. Consider adding a post-install verification step

---

Thank you for this excellent framework! Once the hooks are manually configured, everything works beautifully. Just wanted to report this installer issue to help future Windows users.

cc: @satoastshi