Nix Scaffold -- shell.nix / flake.nix Authoring and Repair

Scaffolds a clean Nix dev environment or diagnoses failures in an existing one. Respects these hard rules:

• Never add verbose echos to shellHook - only what's strictly needed (e.g. setting env vars, exporting paths). No "Welcome to..." banners, no status spam.
• If a shell.nix or flake.nix already exists, use it - do not replace it without the user's explicit approval. Diagnose and patch instead.
• Prefer shell.nix for simple dev shells. Only reach for flake.nix if the project already uses flakes or the user asks for flake output.

When to use

• User asks to "make a shell.nix", "add a nix dev shell", "pin nixpkgs"
• nix-shell / nix develop fails with a cryptic error (hash mismatch, missing attribute, eval error)
• Migrating channels (e.g. 24.11 -> 25.05 -> unstable)
• User pastes a Nix error and asks what's wrong

Procedure

Step 1: Survey the project

Before writing anything, check what exists:

ls shell.nix flake.nix flake.lock default.nix .envrc 2>/dev/null

Also look for language hints to choose sensible buildInputs: Cargo.toml, pyproject.toml, package.json, CMakeLists.txt, go.mod, Justfile, .tool-versions.

If files already exist, read them first. Do not overwrite.

Step 2a: Scaffolding a new shell.nix

Minimal, pinned template. Fill in buildInputs based on what you found in Step 1:

{ pkgs ? import (fetchTarball {
    # Pin to a specific nixpkgs revision. Update the URL + sha256 together.
    url = "https://github.com/NixOS/nixpkgs/archive/<REV>.tar.gz";
    sha256 = "<SHA256>";
  }) {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [
    # language toolchain
    # build tools (just, cmake, ...)
    # test/lint tools
  ];

  # Omit shellHook entirely unless strictly required.
  # If needed, add it here - only env exports, no echos/banners.
}

If a Justfile exists in the project, ensure just is in buildInputs (otherwise recipes won't run inside the shell).

To get a current pinned rev + hash, run (once, to fill in the template). Pick the current stable branch - check https://channels.nixos.org/ if unsure which is current:

CHANNEL="nixos-25.05"   # substitute current stable
REV=$(curl -s "https://api.github.com/repos/NixOS/nixpkgs/commits/${CHANNEL}" | jq -r .sha)
SHA=$(nix-prefetch-url --unpack "https://github.com/NixOS/nixpkgs/archive/${REV}.tar.gz")
echo "REV=$REV SHA=$SHA"

If nix-prefetch-url isn't available, fall back to letting Nix fail once and copy the got: hash from the error.

If the project uses .envrc with use nix or use flake, warn the user that changes will take effect on the next direnv allow (or direnv reload).

Step 2b: Diagnosing a broken shell.nix / flake.nix

Run the evaluator and capture the real error:

nix-shell --run true 2>&1 | tail -50
# or for flakes:
nix develop --command true 2>&1 | tail -50

Common failure modes and fixes:

For flakes, also check flake.lock staleness:

nix flake metadata 2>&1 | head -20
nix flake update --commit-lock-file   # only if user wants to bump

Step 3: Validate

After any change, confirm the shell actually enters:

nix-shell --run 'echo OK && which just cargo python3 2>/dev/null'
# or
nix develop --command bash -c 'echo OK'

If validation fails, loop back to Step 2b with the new error. Do not claim success until the shell enters cleanly.

Step 4: Report

Summarize in this format:

## Nix Shell Status

**State:** <NEW | PATCHED | DIAGNOSED-NOT-FIXED>

**Changes:**
- shell.nix: <created | pinned rev updated | added N buildInputs | ...>

**Validation:** `nix-shell --run true` exits 0

**Notes:**
- <anything the user should know: channel chosen, inputs deliberately omitted, etc.>

If you could not fix it, say so plainly and state what would be needed (e.g. "pinned rev is no longer in nixpkgs history; user must choose a replacement channel").

Anti-patterns (do NOT produce these)

• shellHook that echos a welcome banner, PS1 changes, figlet, environment listings
• Including an empty shellHook = ''''; block when no hook is needed - just omit it
• with pkgs; at top-level scope (outside list context) - causes infinite-recursion eval errors
• Unpinned import <nixpkgs> {} in a project that needs reproducibility
• Mixing fetchTarball pins with flake.nix (pick one mechanism)
• Overwriting an existing shell.nix "to clean it up" without being asked
• Adding packages "just in case" - only what the project actually needs

Tone

If the existing shell.nix / flake.nix already works, say so and don't touch it. Don't rewrite something that isn't broken just because it could be styled differently.