Package placement

Where each tool belongs across nix-darwin, nix-ai, nix-home, and nix-devenv — and when to skip declaration entirely with nix run.

Prefer the most ephemeral install that still meets the tool’s real requirements. Promote upward only when running on demand is too slow.

Across the four Nix repos and the ephemeral options on top, every tool has exactly one correct home. The matrix below is ordered the same way you should read it: always-on at the top, ephemeral at the bottom. Work upward from the bottom and stop at the first row that actually satisfies the tool’s needs.

Placement decision matrix

Package category	Correct home	Mechanism
Core bootstrapping (git, gnupg, vim)	nix-darwin	environment.systemPackages
macOS-only system tools (mas, mactop)	nix-darwin	environment.systemPackages
macOS system-level C libs (sox, portaudio)	nix-darwin	environment.systemPackages
GUI apps unavailable in nixpkgs	nix-darwin	homebrew.casks
CLI tools unavailable in nixpkgs or version-pinned	nix-darwin	homebrew.brews
AI tools, MCP servers, speech / audio stack	nix-ai	home.packages
User dev tools, shell config, linters, credentials	nix-home	home.packages
Pre-commit hook tools (must be on PATH globally)	nix-home	home.packages
Project-specific toolchains	nix-devenv	importable module
Language-specific testers, CI linters (bats, actionlint)	nix-devenv	shell buildInputs
Occasional one-off tools (diagramming, previews)	ephemeral	nix run nixpkgs#<pkg>
npm-backed CLI tools	ephemeral	bunx <pkg>@version
Python CLI tools	ephemeral	uvx <pkg>

Critical rules

homebrew.brews stays in nix-darwin. Home-manager (nix-ai, nix-home) cannot declare Homebrew formulas — homebrew.* is a nix-darwin option only. Group AI-adjacent brew tools with a # AI tools comment block for logical clarity, not a repo move.

Pre-commit hooks with language: system require the tool on PATH. If a tool is used as a language: system pre-commit hook, it must stay in nix-home’s home.packages even if it feels project-specific (lychee, for example).

IDE linters stay global. Tools like pyright that IDEs invoke as background processes must be in home.packages (always on PATH). Moving them to a project devenv shell breaks editor integration because IDEs activate the system environment, not a project shell.

On-demand patterns

# Zero-install ephemeral runs (like bunx but for Nix):
nix run nixpkgs#d2 -- input.d2 output.svg
nix run nixpkgs#mermaid-cli -- -i input.mmd -o output.svg
nix run nixpkgs#python3Packages.grip -- README.md

# Enter a project shell with tools available:
nix develop github:JacobPEvans/nix-devenv?dir=shells/ansible
nix develop github:JacobPEvans/nix-devenv?dir=shells/kubernetes

# Use uvx for Python CLIs (preferred over pipx in Nix):
uvx aider-chat
uvx ruff check .

Repo responsibilities

Repo	Scope
nix-darwin	macOS system config: system packages, Homebrew, security, GUI apps, LaunchDaemons
nix-ai	AI tool ecosystem: Claude Code, Gemini, MCP servers, whisper stack, AI CLIs
nix-home	User dev environment: dev tools, shell config, git, linters, credentials
nix-devenv	Reusable project shells and importable modules: per-language toolchains

Full package lists live in each repo — this page carries placement logic only. Adding a repo to this set means updating the matrix categories above and the AGENTS.md of every consumer repo that references the rule.

Where to go next

Nix Ecosystem overview

The four-repo split and how the layers compose at activation time.

nix-darwin

macOS system config — where homebrew.brews legitimately lives.

nix-ai

AI tool ecosystem — what home.packages carries in the AI tier.

nix-devenv

Reusable per-language project shells and importable modules.