Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt

Use this file to discover all available pages before exploring further.

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 categoryCorrect homeMechanism
Core bootstrapping (git, gnupg, vim)nix-darwinenvironment.systemPackages
macOS-only system tools (mas, mactop)nix-darwinenvironment.systemPackages
macOS system-level C libs (sox, portaudio)nix-darwinenvironment.systemPackages
GUI apps unavailable in nixpkgsnix-darwinhomebrew.casks
CLI tools unavailable in nixpkgs or version-pinnednix-darwinhomebrew.brews
AI tools, MCP servers, speech / audio stacknix-aihome.packages
User dev tools, shell config, linters, credentialsnix-homehome.packages
Pre-commit hook tools (must be on PATH globally)nix-homehome.packages
Project-specific toolchainsnix-devenvimportable module
Language-specific testers, CI linters (bats, actionlint)nix-devenvshell buildInputs
Occasional one-off tools (diagramming, previews)ephemeralnix run nixpkgs#<pkg>
npm-backed CLI toolsephemeralbunx <pkg>@version
Python CLI toolsephemeraluvx <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

RepoScope
nix-darwinmacOS system config: system packages, Homebrew, security, GUI apps, LaunchDaemons
nix-aiAI tool ecosystem: Claude Code, Gemini, MCP servers, whisper stack, AI CLIs
nix-homeUser dev environment: dev tools, shell config, git, linters, credentials
nix-devenvReusable 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.