> ## 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.

# 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`              |
| Host-specific AI provider adapters                           | consumer-specific flake | Home Manager module          |
| 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.

**Provider adapters follow the endpoint.** If an AI CLI is generally useful, package
the CLI in `nix-ai`. If the config bakes in a private gateway URL, model aliases,
or token source, put that adapter module in the consuming host or workstation
flake instead. The public package stays reusable; the private topology stays out
of shared package docs.

## On-demand patterns

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Nix Ecosystem overview" icon="snowflake" href="/nix/overview">
    The four-repo split and how the layers compose at activation time.
  </Card>

  <Card title="nix-darwin" icon="apple" href="/nix/nix-darwin">
    macOS system config — where `homebrew.brews` legitimately lives.
  </Card>

  <Card title="nix-ai" icon="bot" href="/nix/nix-ai">
    AI tool ecosystem — what `home.packages` carries in the AI tier.
  </Card>

  <Card title="nix-devenv" icon="cubes" href="/nix/nix-devenv">
    Reusable per-language project shells and importable modules.
  </Card>
</CardGroup>