MCP server hangs on startup in WSL2 + NTFS due to fs.watch

[mengfanbo123]

Problem

When running codegraph serve --mcp inside opencode on WSL2 with the project on an NTFS mount (/mnt/d), the MCP server fails to start within opencode's 30-second initialization timeout. The same command works fine from a regular terminal (~440ms startup).

Environment

• OS: WSL2 (Ubuntu) on Windows 11
• Filesystem: NTFS via /mnt/d mount
• Node: v24.14.1
• CodeGraph: v0.7.12 (installed via npx @colbymchenry/codegraph)
• Harness: opencode (MCP stdio)
• Project: ~350 source files (Rust), no target/ in index (excluded)

Root Cause

The FileWatcher.start() method in dist/sync/watcher.js calls:

fs.watch(this.projectRoot, { recursive: true }, callback);

On NTFS mounts in WSL2, fs.watch({ recursive: true }) is extremely slow — even with only ~350 tracked source files. This blocks the MCP stdio handshake long enough to trigger opencode's 30s startup timeout.

Notably, this is not a cold-start or large-project issue. The project has no target/, no node_modules/, and only 352 source files. The slowness is intrinsic to recursive fs.watch on NTFS.

Current Workaround

I patched watcher.js to check for a CODEGRAPH_NO_WATCH environment variable:

start() {
    if (process.env.CODEGRAPH_NO_WATCH === '1') {
        console.error('[codegraph] File watching disabled via CODEGRAPH_NO_WATCH=1');
        return false;
    }
    // ... original code
}

And set the env var in opencode config:

"codegraph": {
    "type": "local",
    "command": ["codegraph", "serve", "--mcp"],
    "enabled": true,
    "environment": { "CODEGRAPH_NO_WATCH": "1" }
}

This works perfectly — MCP starts in ~180ms, all tools function normally. The trade-off is no auto-sync on file changes (requires manual codegraph sync).

Suggested Fix

Add official support for disabling the file watcher:

1. Environment variable: CODEGRAPH_NO_WATCH=1 — skip fs.watch entirely
2. CLI flag: codegraph serve --mcp --no-watch
3. Auto-detection: Detect WSL2 + NTFS (/mnt/*) and warn/skip watcher automatically

Option 1 is the least invasive and would solve this for all harness tools, not just opencode.

Related

• Wrong OpenCode init #186 (opencode init config issues)
• v0.7.10 changelog mentions WSL2 timeout fix, but that only addressed Claude Code's timeout behavior — the underlying fs.watch slowness on NTFS remains

[colbymchenry]

Fixed in #210 — thank you @mengfanbo123, this was a textbook bug report. Your root-cause analysis (recursive fs.watch stalling on the /mnt 9p/drvfs boundary, not a cold-start or project-size issue) was spot on, and your CODEGRAPH_NO_WATCH workaround is now the official escape hatch.

What landed:

• Auto-detect — CodeGraph now detects WSL2 + a /mnt/* project path and skips the watcher automatically, so a fresh install just works without any env var.
• CODEGRAPH_NO_WATCH=1 and codegraph serve --mcp --no-watch to force it off anywhere, plus CODEGRAPH_FORCE_WATCH=1 to override the auto-detect if your /mnt setup is actually fast.
• Since auto-sync is off in that mode, codegraph init / codegraph install now offer to keep the index fresh via git hooks (post-commit / post-merge / post-checkout running codegraph sync in the background) or fully manual sync — and either way it tells you the index stays frozen until you re-sync.

This will ship in the next release. Thanks again for the detailed report and the workaround! 🙏