feat: Add Nix flake for reproducible devenv.sh integration

[tburny]

feat: Add Nix flake for reproducible devenv.sh integration

Problem

Running nWave inside a Docker container built by devenv.sh requires manual workarounds because the nwave-ai package installs via pipx/uv into host-specific paths that don't exist inside Nix-built containers.

The DES hooks in ~/.claude/settings.json reference a hardcoded Python binary path:

$HOME/.local/share/pipx/venvs/nwave-ai/bin/python -m des.adapters.drivers.hooks.claude_code_hook_adapter

Inside a devenv container:

• HOME is /env (not /home/user)
• The pipx venv doesn't exist (Nix manages packages differently)
• The host's Python binary can't run inside the container (different glibc, different Nix store paths)

Current workaround

We have to create a Python shim at the expected path that delegates to the container's python3:

VENV_BIN="/env/.local/share/pipx/venvs/nwave-ai/bin"
mkdir -p "$VENV_BIN"
printf '#!/usr/bin/env bash\nexec python3 "$@"\n' > "$VENV_BIN/python"
chmod +x "$VENV_BIN/python"

And build a custom Nix derivation for the nwave-ai wheel:

# nix/nwave-ai.nix
buildPythonPackage rec {
  pname = "nwave-ai";
  version = "3.12.0";
  format = "wheel";
  src = fetchurl {
    url = "https://files.pythonhosted.org/packages/.../nwave_ai-${version}-py3-none-any.whl";
    hash = "sha256-...";
  };
  # ... dependencies
}

Plus mount ~/.claude/lib/python/ into the container for the des module, which is installed separately by nwave-ai install.

This is fragile -- it breaks on every nwave version bump, and the hash must be updated manually.

Proposal

Add a flake.nix to the nWave repository (or a separate nwave-nix repo, similar to claude-code-nix) that provides:

1. A Nix package

# Usage in devenv.nix
{ pkgs, inputs, ... }:
{
  packages = [
    inputs.nwave.packages.${pkgs.system}.default
  ];
}

This should include:

• The nwave-ai CLI binary
• All DES CLI tools (des-health-check, des-init-log, des-log-phase, des-roadmap, des-verify-integrity)
• The des Python module (currently installed separately into ~/.claude/lib/python/)
• A proper Python wrapper that doesn't depend on pipx/uv venv paths

2. A nixpkgs overlay

overlays = [ inputs.nwave.overlays.default ];
# Then: pkgs.nwave-ai

3. (Optional) A devenv module

{ inputs, ... }:
{
  imports = [ inputs.nwave.devenvModules.default ];
  nwave.enable = true;
}

This module would:

• Add nwave-ai and DES tools to the devenv PATH
• Configure the Claude Code hooks with Nix store paths instead of pipx paths
• Make the des Python module available via PYTHONPATH
• Work inside devenv container build images without shims

4. Automated updates

Similar to claude-code-nix, a GitHub Action that checks PyPI for new releases and auto-updates the flake.

Context

We're running Claude Code autonomously inside devenv Docker containers with --dangerously-skip-permissions for overnight unattended sessions. The nWave DELIVER wave runs inside the container, executing TDD steps via subagents. This requires all nWave infrastructure (DES hooks, CLI tools, Python modules) to be available inside the Nix-built container.

The current approach works but requires:

• A custom Nix derivation for the wheel (breaks on version bumps)
• A Python shim at the pipx path (fragile, container-specific)
• Manual mounting of ~/.claude/lib/python/ (the des module)
• Manual mounting of ~/.claude/ (agents, skills, commands installed by nwave-ai install)

A proper Nix flake would make nWave a first-class citizen in Nix-based dev environments, eliminating all these workarounds.

Environment

• OS: Ubuntu 24.04 (host), NixOS (devenv containers)
• devenv.sh: latest
• nwave-ai: 3.12.0
• Claude Code: 2.1.84 (via claude-code-nix)
• Container: built via devenv container build shell

[11PJ11]

Thanks for the detailed proposal, @tburny — the use case is clear (Claude Code in Nix-managed devenv containers, where pipx-based hooks don't survive the container boundary).

We're evaluating Nix support but haven't decided yet on whether to ship a flake in-tree, recommend a community-owned nwave-nix repo (mirroring claude-code-nix), or both. Maintenance burden vs. user value is the open question on our side.

If you'd like to move ahead, a draft PR is welcome — even just the flake.nix skeleton without the devenv module / overlay / auto-update would let us evaluate the surface concretely. We'll engage on the design in the PR.

Tagging enhancement for now.

---

🤖 AI-assisted draft, reviewed and posted by @11PJ11.