Support for NixOS (packaging as Nix package or easy overlay)

[Yury-Zakharov]

Goal
I would like to use CodeGraph on NixOS. Ideally it should be available either as an official Nix package or at least easy to package/maintain as an overlay without major workarounds.
What was tried
I spent significant time trying to integrate CodeGraph into a Nix-based development environment using both available distribution methods:

Standalone binary (codegraph-linux-x64.tar.gz)
npm package (@colbymchenry/codegraph)

Problems encountered

1. Standalone binary distribution

• The tarball contains a dynamically linked node binary.

• On NixOS this immediately fails with:

Could not start dynamically linked executable: .../node
NixOS cannot run dynamically linked executables intended for generic linux environments out of the box.

• Required manual use of patchelf (via autoPatchelfHook + postFixup) to rewrite the dynamic linker and rpath.
• Even after patching, creating a reliable wrapper script was fragile due to how the tarball is structured (bin/node + lib/ + entrypoint logic).
• The binary works after heavy patching, but this is not a sustainable or user-friendly solution.

2. npm package

• Running npm install @colbymchenry/codegraph only pulls 2 packages.
• The package declares optionalDependencies for platform-specific natives (@colbymchenry/codegraph-linux-x64, etc.).
  These native packages also contain a dynamically linked node binary → same NixOS linker error appears.
• The npm-shim.js entrypoint leads to silent failures or long hangs with no output when the native component is missing or broken.
• The package does not appear to be designed as a fully self-contained CLI for environments that manage dependencies declaratively (such as Nix).

Why this is happening

• Both distribution methods ship (or depend on) a dynamically linked Node.js binary built against a generic glibc.
• NixOS uses a completely different dynamic linker and library model, so any prebuilt binary that is not statically linked or explicitly patched will fail.
• The npm package treats the platform natives as optional, so they are easily skipped in automated/CI/Nix environments.
• There is currently no official Nix package, overlay, or documentation for packaging CodeGraph on NixOS.

Suggested directions
To make CodeGraph work well on NixOS, I would appreciate if the project could consider one or more of the following:

• Provide a statically linked binary (or at least one that is easy to patch with patchelf).
• Make the platform-specific packages regular dependencies instead of optionalDependencies when publishing the npm package (so the native component is always installed for CLI usage).
• Add a small section in the documentation about NixOS / declarative environments.
• Consider maintaining a simple official overlay (or at least a flake.nix example) so users don’t have to reverse-engineer the packaging.

Would the maintainers be open to accepting contributions or guidance in this area?