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
defaultshell 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,
ghandclaudebelong on the machine. Runtimes and build tools belong to the project, pinned by itsflake.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-lineflake.nixand 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
claudeinside 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
- Assumes NixOS.
js-devshell.nixsetsPLAYWRIGHT_BROWSER_PATH=/run/current-system/sw/bin/brave, a path that only exists on NixOS. Comments inshell-tools.nixsay tools are “ALREADY on this system”, meaning the Sys76, not this machine or the Mac. - Likely bug:
NPM_CONFIG_PREFIX. Its value is"$HOME/.npm-global", but numtide devshell’svaluefield is shell-escaped (literal).$HOMEnever expands. It needs theevalfield. - Weight every shell pays.
_module.args.pkgsapplies therust-overlayandneovim-nightlyoverlays to the package set all shells share, so evenjsmust fetch those inputs. Thenvminput isn’t used anywhere, and a Node version manager has no job in a Nix shell. - Editors and GUI apps in a devshell.
vscode.nixputs the VS Code app and unfree Copilot extensions intodefault.editors.nixis already disabled because it never evaluated. - The two repos disagree about where tools live.
nixos-hypr-config’shome/mps/dev-tools.nixmoved 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 injs. This machine has no Home Manager. - mise and Nix will compete for
PATH.mise activate bashrewritesPATHat every prompt, and its globalnode = "latest"can end up ahead of a devshell’snodejs_22. Unverified here until Nix is installed, but it’s a known friction point. - No child project has a flake. The root
flake.nixis the only Nix file tracked in the monorepo. A collaborator who clonesastro-knotsorcontent-farmon its own gets nothing. - Minor:
.envrcis tracked even though.gitignorelists.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
jsgets 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 whatmodules/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:
- Start the shell first, then
claude.cdinto the project so direnv loads (or runnix develop), then launchclaudefrom 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. - Let Claude load it with hooks. Claude Code has
SessionStartandCwdChangedhook events. The docs describeCwdChangedas “useful for reactive environment management with tools like direnv”. A hook can rundirenv export bashand 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.jsonat 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
nixpackage withnix-daemon.service, or the upstream/Determinate installer. Check the Arch wiki and Omarchy’s own guidance first. - Enable
nix-commandandflakesinnix.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 globalnode, 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(useeval, or drop it). - Remove the NixOS-only
PLAYWRIGHT_BROWSER_PATH, or make it per-machine through.envrc.local. - Stop applying
neovim-nightlyandrust-overlayto every shell’spkgs. Drop thenvminput. - Move VS Code, editors, terminal and prompt tools out of devshells.
- Reconcile with
nixos-hypr-config’sdev-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,contentmodules, one file each. - Write
lib.mkProject, plusastroandplain-jstemplates. - 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/denodirectly. - 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+CwdChangedhook writingdirenv export bashto$CLAUDE_ENV_FILE. Confirm the variables reach later Bash commands, and thatcdinto 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(whichCLAUDE.mdsymlinks 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
- Pilot project. Candidates: an Astro Knots site (most representative), or
mpstaton-site (exercises the
bunscripts). - Toolkit location. Its own repo,
lossless-group/lossless-devshells(recommended: independent children, small input, clear ownership), or the monorepo root. - mise’s role on Omarchy. Global CLIs only, or keep global node as well.
- 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.
Related
flake.nix,flake-modules/,.envrc,.envrc.local.exampleat the monorepo roothome/mps/dev-tools.nixin mpstaton/nixos-hypr-config- [[Maintain-a-Current-README-and-other-Docs]]: README and
AGENTS.mdupdates in Phases 3 and 5 - [[pseudomonorepos]]: why child repos must work standalone
References
- Dendritic design with flake-parts, FAQ: https://github.com/Doc-Steve/dendritic-design-with-flake-parts/wiki/FAQ
- Vic’s Dendritic Nix ecosystem: https://dendritic.oeiuwq.com/
- vic/flake-aspects: https://github.com/vic/flake-aspects
- Claude Code hooks documentation: https://code.claude.com/docs/en/hooks
- CLAUDE_ENV_FILE not provided to SessionStart hooks (anthropics/claude-code #15840): https://github.com/anthropics/claude-code/issues/15840
- CLAUDE_ENV_FILE written but not sourced (anthropics/claude-code #27987): https://github.com/anthropics/claude-code/issues/27987
- numtide devshell module options: https://numtide.github.io/devshell/modules_schema.html