All writing

Operating note3 min read

Leaving Nix Home Manager for Mise (and making AI agents obey it)

Why I replaced my Nix flake setup with mise.toml, a Brewfile, and a few boring shell scripts — plus the AGENTS.md rule that stops coding agents from installing packages behind my back.

For a while I ran my machines out of a Nix Home Manager flake. On good days it felt wonderfully clean and reproducible. On bad days — usually ten minutes before a meeting when I just wanted to install one CLI tool or bump Node — I was staring at a stack trace inside a Nix expression wondering why I’d turned setting up a laptop into a second job.

I finally moved everything over to Mise (machines/mise-config inside my personal repo), a Brewfile, and a handful of small, readable scripts. I haven’t missed Nix once.

The problem with Nix for a personal setup

Nix is brilliant when you genuinely need bit-for-bit reproducible builds across a fleet. For my own MacBook and Linux boxes, though, I was paying the complexity tax every single week for guarantees I barely used:

  • Want to tweak a shell alias or test a new tool quickly? Edit the flake, wait for evaluation, rebuild the generation, hope nothing upstream broke a Darwin overlay.
  • Something fails halfway through an upgrade? Now you’re debugging Nixpkgs internals instead of doing whatever you actually sat down to work on.
  • Handing the repo to an AI coding agent? Agents are pretty good at editing mise.toml and Brewfile. They are much worse at guessing which obscure Home Manager module option changed name three months ago.

I realised what I actually wanted wasn’t "purely functional OS management". I just wanted one obvious place where every tool and config file is declared, so a new machine gets set up in ten minutes and stays boring to maintain.

The split that replaced it

The whole mise-config setup now fits in a mental model you can hold in your head without checking docs:

Responsibility Where it lives
Portable CLI tools & runtimes mise.toml (pinned via mise.lock)
macOS apps & native packages Brewfile (applied via mise run system-packages)
Dotfiles & shell config config/ (linked into ~, with timestamped backups first)
Small personal helpers bin/
One-off transitions & OS glue migrations/ and scripts/

Notice there’s no magic generation store. If apply is about to replace a file in my home directory, it saves a timestamped backup first. If anything looks wrong, recovery is copying a normal file back — not figuring out which symlink generation to roll back to.

One nice subtle detail: the first-time bootstrap runs ./scripts/check and ./scripts/apply directly rather than calling mise run immediately. That avoids Mise’s task auto-install trying to compile language runtimes before Homebrew has installed the native build dependencies they need. After that initial run, updating everything from any directory is just miseup.

The unexpected twist: making AI agents obey it

Once your machine is cleanly declarative again, there’s a brand-new way it quietly drifts out of sync in 2026: AI coding agents.

Ask an agent to build an iOS project or lint a script and, if a tool is missing, its very first instinct is to run brew install xcodegen or npm install -g ... straight in the terminal. That fixes the immediate error and immediately breaks your tidy declarative setup.

The fix turned out to be dead simple — six lines right in my root AGENTS.md:

markdown
## Installing software on Henry's machines

Do not run `brew install`, `npm install -g`, or similar commands directly. Declare
the tool in `machines/mise-config`, then apply it from that directory:

- macOS apps and native packages: add them to `machines/mise-config/Brewfile`.
  For a third-party cask, also add its `tap` line. Then run `mise run system-packages`.
- Command-line tools that Mise can manage: add them to the `[tools]` section of
  `machines/mise-config/mise.toml`, then run `mise run apply`.

It works shockingly well. Instead of mutating my machine in the background, agents now add the package to Brewfile or mise.toml, run mise run apply, and leave a clean Git diff I can actually see.

Boring tools win twice: they’re easier for me to maintain at 9pm on a Tuesday, and they’re way easier for agents to work with without breaking anything.