Windows compatibility issue: process.env.HOME undefined causes startup crash

[valentt]

Environment

• OS: Windows 11 (also affects Windows 10)
• Node.js: v22.20.0
• Package Version: @siteboon/claude-code-ui (latest from npm)
• Installation Method: npm install -g @siteboon/claude-code-ui

Bug Description

The application crashes immediately after starting on Windows with the following error:

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined
at Object.join (node:path:528:7)
at setupProjectsWatcher (file:///C:/Users/.../node_modules/@siteboon/claude-code-ui/server/index.js:59:37)

Root Cause

The setupProjectsWatcher function assumes the HOME environment variable exists, which is a Unix/Linux convention. Windows uses USERPROFILE
instead, causing process.env.HOME to be undefined.

Problematic code (server/index.js:59):

async function setupProjectsWatcher() {
    const chokidar = (await import('chokidar')).default;
    const claudeProjectsPath = path.join(process.env.HOME, '.claude', 'projects');
    // ...
}

Steps to Reproduce

1. Install on Windows: npm install -g @siteboon/claude-code-ui
2. Create .env file with PORT=3001 and CLAUDE_PROJECTS_DIR=C:\Users\[username]\.claude\projects
3. Run: claude-code-ui
4. Observe crash with ERR_INVALID_ARG_TYPE

Expected Behavior

Application should start successfully on Windows and watch the Claude projects directory.

Proposed Fix

Use cross-platform environment variable detection and respect CLAUDE_PROJECTS_DIR:

async function setupProjectsWatcher() {
    const chokidar = (await import('chokidar')).default;
    const claudeProjectsPath = process.env.CLAUDE_PROJECTS_DIR ||
        path.join(process.env.HOME || process.env.USERPROFILE || process.env.HOMEPATH, '.claude', 'projects');

    if (projectsWatcher) {
        projectsWatcher.close();
    }
    // ...
}

This fix:
1. ✅ Respects CLAUDE_PROJECTS_DIR environment variable (already in .env)
2. ✅ Falls back to HOME on Unix/Linux/macOS
3. ✅ Falls back to USERPROFILE on Windows
4. ✅ Additional fallback to HOMEPATH for edge cases

Workaround (Temporary)

Manually set HOME environment variable before running:
$env:HOME = $env:USERPROFILE
claude-code-ui

Or edit server/index.js:59 directly in the installed package.

Impact

- Severity: Critical - Application cannot start on Windows without manual code modification
- Affected Users: All Windows users
- Platform: Windows 10/11 (any Windows version)

Additional Context

This is a common cross-platform issue in Node.js applications. The Node.js os.homedir() function is the recommended cross-platform way to get the home
directory, which internally handles these differences.

Alternative fix using os.homedir():
import os from 'os';

async function setupProjectsWatcher() {
    const chokidar = (await import('chokidar')).default;
    const claudeProjectsPath = process.env.CLAUDE_PROJECTS_DIR ||
        path.join(os.homedir(), '.claude', 'projects');
    // ...
}

---

**Additional files to check for similar issues:**
- Search codebase for other instances of `process.env.HOME`
- Verify all path operations use cross-platform methods