macOS: codegraph serve opens excessive file descriptors and causes system instability

[yuadsl3010]

Environment

• OS: macOS
• codegraph version: 0.9.6
• Install: npm global package @colbymchenry/codegraph
• Runtime observed: bundled codegraph-darwin-arm64/node

Problem

On macOS, codegraph serve --mcp appears to hold an extremely large number of open files. This eventually causes system-level abnormal behavior / instability.

Two running codegraph MCP server processes were the top file descriptor users:

lsof -n 2>/dev/null | awk '{print $2}' | sort | uniq -c | sort -nr | head -20
  61446 50283
  52886 50731
    578 4720
    502 4693
    424 60277
    ...

Process details:
PID 50283:
codegraph.js serve --mcp --path /Users/yuzhenchuan/code/food
Open files: 61446

PID 50731:
codegraph.js serve --mcp
Open files: 52886

Full process command:
/Users/yuzhenchuan/.nvm/versions/node/v18.20.8/lib/node_modules/@colbymchenry/codegraph/node_modules/@colbymchenry/codegraph-darwin-arm64/node --liftoff-only .../codegraph.js serve --mcp --path /Users/yuzhenchuan/code/food

Expect: codegraph serve --mcp should not keep tens of thousands of files open persistently, especially on macOS where file descriptor limits can affect the whole user session.
Actual: MCP server processes held ~61k and ~53k open files respectively. I had to kill them manually:

kill -9 50283 50731

Please investigate whether the macOS file watcher / indexing path is leaking file descriptors or watching too many files without filtering ignored directories such as .git, node_modules, generated files, or large dependency trees.

[AriaShishegaran]

I reproduced the same class of macOS instability on CodeGraph 0.9.8 with sanitized details added to #496. Short version:

• macOS 26.5 / Darwin 25.5.0, Apple Silicon arm64
• kern.maxfiles: 491520
• kern.maxfilesperproc: 245760
• Multiple codegraph serve --mcp --path <project> daemons from agent workflows
• Largest project daemon: 2901 numeric FDs, mostly regular files (REG 2887)
• A second project daemon: 599 numeric FDs, mostly regular files
• Daemon logs included repeated ENFILE: file table overflow errors from realpath, lstat, and scandir
• Killing stale/high-FD CodeGraph project daemons dropped kern.num_files from 15771 to 12164
• Adding --no-watch to MCP configs was the effective mitigation

This was not as extreme as the original 50k/60k examples here, but it matters because it happened even after using per-project indexes rather than one huge root-level workspace. The cumulative multi-project agent workflow is enough to cause system-level symptoms unless users manually detect and kill CodeGraph daemons.

I also opened a guardrail/defaults follow-up here: #628

[colbymchenry]

Fixed in #650.

Root cause, confirmed by reproducing with lsof (your evidence was spot on): the file watcher (chokidar v4) held one OS file descriptor per watched file on macOS. fsevents is installed but chokidar v4 no longer uses it, so it fell back to a kqueue watch that registers an fd per file — tens of thousands on a large project, which exhausted kern.maxfiles and spilled over into unrelated processes failing with "too many open files."

The fix drops chokidar for a single native recursive fs.watch on macOS/Windows, which costs 0 extra descriptors regardless of repo size (verified at 6,000 and 12,000 files), and one inotify watch per directory on Linux instead of per file. Closing as fixed by #650 — thanks for the report.