Finally implementing Nix devshells

Clone any Lossless project, cd in, and the right node, pnpm and bun are already there, on Linux or a Mac, for us or a collaborator.

Path
plans/Finally-Implementing-Nix-Devshells.md
Authors
Michael Staton
Augmented with
Claude Code on Claude Opus 5 (1M context)
Tags
Nix · Nix-Flakes · Devshells · Direnv · Developer-Environment · Reproducibility · Claude-Code · Pseudomonorepos

Finally implementing Nix devshells

Why Care?

Every project in this tree assumes a toolchain: Astro sites need a particular Node plus pnpm, a few scripts call bun directly, and jsr publish quietly needs Deno. Today that toolchain lives in whoever’s machine happens to have it. A collaborator who clones one repo gets a README and a guessing game. When a tool is missing, things often fail silently: a port-clearing script no-ops without lsof, and a preview harness serves the wrong build under the right label.

A Nix devshell fixes that. It’s roughly a virtualenv for the whole toolchain, declared in a file and pinned by a lockfile. With direnv, you cd into a project and the exact tools it needs appear on PATH. You cd out and they’re gone. It works the same on Linux and macOS, for us and for anyone we invite in.

We started this once. There’s a flake at the monorepo root. This plan is about finishing it properly: across three machines (Mac workhorse, NixOS Sys76, Omarchy), for every project, and in a form a collaborator can use without knowing any of this history.

TL;DR

  • One flake holding everything isn’t the problem. Nix only builds the shell you enter. The problems are that the root default shell is a kitchen sink, child projects have no shell of their own, and the flake assumes NixOS.
  • Split machine tools from project tools. Editors, terminals, gh and claude belong on the machine. Runtimes and build tools belong to the project, pinned by its flake.lock.
  • Shared toolkit plus a tiny flake per project. A small shared flake offers building blocks (js, rust, python, jsr). Each child repo gets a ~15-line flake.nix and a one-line .envrc.
  • Dendritic is for host configs, not devshells. Borrow its one-file-per-concern idea for the toolkit. Save the real pattern for unifying the three machines’ system configs later.
  • Claude Code: launch claude inside the shell, or have hooks load direnv into Claude’s Bash environment. Test the hook route on this machine first.

Current state (reviewed 2026-09-13)

The machine

Omarchy (Arch Linux, Hyprland), bash. As of this review:

Tool State
nix, /nix Not installed
direnv, nix-direnv Not installed
mise Installed by Omarchy and turned on in every bash session. Manages node (26.8.2, latest), claude, codex, gh globally
git, gh, python3 Present
pnpm, bun, uv Not installed

The root flake

flake.nix uses flake-parts plus numtide devshell, pins nixpkgs to the nixos-unstable branch (with a good comment on why not the registry alias), and imports modules from flake-modules/. It defines three shells:

Shell Contents Verdict
default git and CLI tools, plus Rust stable and 6 cargo tools, cmake/make/ninja, the VS Code app with Copilot extensions, Helix (from its own flake), neovim, zsh/fish, starship, gonzo. Built from flake.nix’s own list merged with devshell.nix, rust.nix and vscode.nix A kitchen sink. Most of it is machine-level
js nodejs_22, pnpm, bun, deno, typescript, typescript-language-server, lsof, psmisc, plus delta/aha/duf/yq from shell-tools.nix A good core
tools delta, aha, duf, yq Fine

.envrc deliberately does not auto-load a shell. .envrc.local.example lets a machine opt in with use flake .#js.

Problems found

  1. Assumes NixOS. js-devshell.nix sets PLAYWRIGHT_BROWSER_PATH=/run/current-system/sw/bin/brave, a path that only exists on NixOS. Comments in shell-tools.nix say tools are “ALREADY on this system”, meaning the Sys76, not this machine or the Mac.
  2. Likely bug: NPM_CONFIG_PREFIX. Its value is "$HOME/.npm-global", but numtide devshell’s value field is shell-escaped (literal). $HOME never expands. It needs the eval field.
  3. Weight every shell pays. _module.args.pkgs applies the rust-overlay and neovim-nightly overlays to the package set all shells share, so even js must fetch those inputs. The nvm input isn’t used anywhere, and a Node version manager has no job in a Nix shell.
  4. Editors and GUI apps in a devshell. vscode.nix puts the VS Code app and unfree Copilot extensions into default. editors.nix is already disabled because it never evaluated.
  5. The two repos disagree about where tools live. nixos-hypr-config’s home/mps/dev-tools.nix moved bun, deno, lsof, psmisc and direnv/nix-direnv into Home Manager on purpose (“the build command should just work”). The monorepo flake still carries them in js. This machine has no Home Manager.
  6. mise and Nix will compete for PATH. mise activate bash rewrites PATH at every prompt, and its global node = "latest" can end up ahead of a devshell’s nodejs_22. Unverified here until Nix is installed, but it’s a known friction point.
  7. No child project has a flake. The root flake.nix is the only Nix file tracked in the monorepo. A collaborator who clones astro-knots or content-farm on its own gets nothing.
  8. Minor: .envrc is tracked even though .gitignore lists .envrc.

The design

1. Machine tools vs project tools

The single most useful rule. Everything goes in exactly one layer:

Layer What goes there How it’s installed
Machine (once per box) nix, direnv + nix-direnv, git, gh, editors, terminal emulators, prompt/shell niceties, claude, codex Omarchy: pacman / mise. Sys76: NixOS + Home Manager. Mac: Homebrew or nix-darwin
Project (per repo) Runtimes and build tools the project’s own scripts call: node, pnpm, bun, deno, rust, uv, plus project-specific extras (imagemagick, sqlite, …) The project’s flake.nix, pinned by its flake.lock, loaded by .envrc

A test for anything on the fence: would pnpm build or a test run fail without it? If yes, it’s a project tool. If it’s just nicer, it’s a machine tool.

2. Shared toolkit plus a tiny flake per project

The toolkit. A small shared flake whose job is to offer reusable devshell building blocks, one file each:

lossless-devshells/
├── flake.nix
├── modules/
│   ├── js.nix        # node, pnpm, bun, typescript, lsof/psmisc
│   ├── jsr.nix       # deno, for `jsr publish`
│   ├── rust.nix      # rust stable + rust-analyzer, cargo tools
│   ├── python.nix    # uv, python
│   └── content.nix   # yq and friends for frontmatter work
├── lib/
│   └── mkProject.nix # picks modules + extras → devShells.default
└── templates/
    ├── astro/        # flake.nix + .envrc for an Astro Knots site
    └── plain-js/

Each project. A ~15-line flake.nix, its own flake.lock, and an .envrc containing use flake. Sketch only; mkProject is what we’d build, and nothing here exists yet:

{
  inputs.lossless.url = "github:lossless-group/lossless-devshells";
  outputs = { lossless, ... }: lossless.lib.mkProject {
    shells = [ "js" ];
    extraPackages = pkgs: [ pkgs.imagemagick ];
  };
}

Adding a project becomes nix flake init -t github:lossless-group/lossless-devshells#astro followed by direnv allow.

Why this shape:

  • Collaborators clone child repos on their own. A child flake that points at ../.. (the monorepo root) breaks for anyone who didn’t clone the whole tree. A GitHub input works everywhere.
  • Each project’s lock pins exact versions. Upgrading one project (nix flake update lossless) can’t break another.
  • Consistency without copy-paste. Common tools are declared once in the toolkit, and every project that picks js gets the same set.

Where the toolkit lives is open decision 2 below. The recommendation is its own small repo. The alternative is to keep it at the monorepo root and have children use github:lossless-group/lossless-monorepo as the input, which works but makes every child depend on the whole anchor repo.

3. Slim the root flake

The monorepo root stays a flake, but a thin one: a shell for work that spans the whole tree (git helpers, yq, just, the skills and changelog scripts). It should use the same toolkit as everything else rather than being its own special case.

4. Where dendritic fits

The “dendritic” pattern (vic’s Dendritic Nix ecosystem, flake-parts plus aspect-oriented modules) organizes Nix config as one file per aspect (ssh, users, editors), each providing config for several classes: NixOS, nix-darwin, Home Manager.

  • It’s aimed at host configs, not devshells. The pattern’s FAQ covers NixOS, nix-darwin and Home Manager and says nothing about devshells.
  • It warns beginners off. The same FAQ says to “take your first steps without following a pattern.”
  • Borrow the core idea for the toolkit: one file per concern, composed. That is what flake-modules/ already does and what modules/ above does.
  • Where it really pays off: unifying nixos-hypr-config (Sys76), a future nix-darwin config (Mac), and Home Manager on Omarchy into one config spanning all three machines. That’s a separate, later project, not part of this plan.

5. Claude Code and devshells

Claude Code’s Bash tool runs each command in a fresh shell built from the environment Claude was started in. It does not re-run direnv on its own when a command cds somewhere. Two ways to give it the project’s tools:

  1. Start the shell first, then claude. cd into the project so direnv loads (or run nix develop), then launch claude from that same terminal. Works with no setup. The environment is fixed at launch, so moving to a project with a different shell doesn’t switch it.
  2. Let Claude load it with hooks. Claude Code has SessionStart and CwdChanged hook events. The docs describe CwdChanged as “useful for reactive environment management with tools like direnv”. A hook can run direnv export bash and append the output to the file named by $CLAUDE_ENV_FILE, which later Bash commands source. That mechanism has had open bugs (not passed to plugin hooks, not sourced on Windows), so test it on this machine before relying on it. It would live in .claude/settings.json at project scope so collaborators get it too.

Fallback that always works, per command: direnv exec . pnpm build or nix develop -c pnpm build.

claude itself is installed by mise, so it’s on PATH with or without a devshell. The shell only has to supply the project’s own tools.

Phases

Each phase ends with something checkable before moving on.

Phase 0: Install Nix on the Omarchy machine

  • Install Nix multi-user (daemon). Options to weigh at install time: Arch’s nix package with nix-daemon.service, or the upstream/Determinate installer. Check the Arch wiki and Omarchy’s own guidance first.
  • Enable nix-command and flakes in nix.conf.
  • Install direnv and nix-direnv, and hook direnv into bash after Omarchy’s mise activation.
  • Decide mise’s scope: keep it for global CLIs (claude, codex, gh) and drop global node, or keep node and confirm the devshell’s node wins inside projects.

Done when: nix --version works, nix flake metadata nixpkgs resolves, and in a scratch dir with use flake a devshell’s node --version beats mise’s.

Phase 1: Make the root flake work off NixOS

  • Fix NPM_CONFIG_PREFIX (use eval, or drop it).
  • Remove the NixOS-only PLAYWRIGHT_BROWSER_PATH, or make it per-machine through .envrc.local.
  • Stop applying neovim-nightly and rust-overlay to every shell’s pkgs. Drop the nvm input.
  • Move VS Code, editors, terminal and prompt tools out of devshells.
  • Reconcile with nixos-hypr-config’s dev-tools.nix: one written rule for what’s a machine tool and what’s a project tool.

Done when: nix flake check passes and nix develop .#js -c node --version works on Omarchy. Also run it on the Mac and the Sys76 when convenient.

Phase 2: Build the shared toolkit

  • Decide location (open decision 2).
  • Extract js, jsr, rust, python, content modules, one file each.
  • Write lib.mkProject, plus astro and plain-js templates.
  • Support x86_64-linux, aarch64-linux, aarch64-darwin, x86_64-darwin.

Done when: nix flake init -t <toolkit>#astro in an empty dir yields a shell with node, pnpm and bun, from cache, in seconds.

Phase 3: Pilot one project

  • Pick the pilot (open decision 1).
  • Add flake.nix, flake.lock, .envrc, and make sure .direnv/ is gitignored.
  • Run the project’s real commands: install, dev, build, and any script that calls bun/deno directly.
  • Update the project’s README “Running locally” section.

Done when: a fresh clone of the pilot on this machine goes from git clone to a green pnpm build with only direnv allow in between.

Phase 4: Claude Code integration

  • Try option 1 (launch inside the shell) and confirm Claude’s Bash tool sees the devshell’s node and pnpm.
  • Try option 2: a project-scope SessionStart + CwdChanged hook writing direnv export bash to $CLAUDE_ENV_FILE. Confirm the variables reach later Bash commands, and that cd into a second project switches them.
  • Record which option we standardize on, and any bug hit.

Done when: a Claude session started outside any shell can pnpm build in the pilot project without being told to enter a shell.

Phase 5: Roll out and document

  • Add flakes to the other active projects, one PR per repo.
  • Update the monorepo root AGENTS.md (which CLAUDE.md symlinks to) with the pattern and the Claude Code approach.
  • Write a blueprint for the pattern once it has survived two or three repos, and a changelog entry per [[changelog-conventions]].
  • Onboarding note for collaborators: install Nix plus direnv, clone, direnv allow.

Open decisions

  1. Pilot project. Candidates: an Astro Knots site (most representative), or mpstaton-site (exercises the bun scripts).
  2. Toolkit location. Its own repo, lossless-group/lossless-devshells (recommended: independent children, small input, clear ownership), or the monorepo root.
  3. mise’s role on Omarchy. Global CLIs only, or keep global node as well.
  4. Claude Code approach. Launch-inside-shell as the documented default, or hooks, pending Phase 4.

Out of scope

  • A dendritic config spanning the Mac, Sys76 and Omarchy machines.
  • Replacing mise or Homebrew wholesale.
  • Packaging project builds themselves as Nix derivations. Shells only.
  • flake.nix, flake-modules/, .envrc, .envrc.local.example at the monorepo root
  • home/mps/dev-tools.nix in mpstaton/nixos-hypr-config
  • [[Maintain-a-Current-README-and-other-Docs]]: README and AGENTS.md updates in Phases 3 and 5
  • [[pseudomonorepos]]: why child repos must work standalone

References