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

# AI tooling

> Every AI coding tool, packaged. Claude Code, Gemini CLI, Copilot, MLX modules, 15+ MCP servers — declarative, reproducible, version-pinned.

export const RepoFit = ({children}) => <Tip>{children}</Tip>;

export const RepoMeta = ({language, status, lastActive, repoUrl}) => <Info>
    Language: <b>{language}</b>  ·  Status: <b>{status}</b>  ·  Last active: <b>{lastActive}</b>  ·  <a href={repoUrl}>Source on GitHub</a>
  </Info>;

> The whole AI toolkit, in one flake. `nix run` and go.

<RepoMeta language="Nix" status="active" lastActive="this week" repoUrl="https://github.com/JacobPEvans/nix-ai" />

`nix-ai` is the package and config layer for everything AI-coding-related. It packages CLIs that don't yet have first-party Nix derivations, pins MCP server versions, and exports overlays the rest of the Nix stack consumes.

Host-specific provider wiring is intentionally outside `nix-ai`. If a tool needs
to point at a private local LLM gateway, package the tool here, then keep the
endpoint and token-source module in the consuming workstation flake. That keeps
reusable packaging public and environment topology private.

## What it does

* Packages Claude Code, Gemini CLI, GitHub Copilot CLI, and assorted AI tooling
* Provides MLX module derivations for Apple Silicon
* Pins 15+ MCP servers and exposes them as reusable Nix attributes
* Exports an overlay so `nix-darwin` and `nix-home` can include AI tools without duplicating logic
* Includes a shell module (`devShells.default`) for "just give me an AI sandbox" workflows

## How it fits

| Feeds into                                                                                            | Consumes                                                                        |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [macOS host](/nix/nix-darwin) overlay, [User environment](/nix/nix-home) packages, ad-hoc `nix shell` | [ai-assistant-instructions](/ai-development/ai-assistant-instructions) rule set |

<RepoFit>
  Anything that's "an AI tool I want everywhere" belongs here. Single-project AI experiments go in a project-local `nix-devenv`-style flake.
</RepoFit>

## Configuration surface

`nix-ai` ships as a reusable flake module with a single knob surface — `modules/maintainer-profile.nix`. This is the one file a consumer touches to adapt the stack:

* **Identity** fields (`user.fullName`, `user.trustedOrgs`) have maintainer defaults so derived values (e.g. Claude auto-mode trusted-org list) stay internally consistent; override them for your own identity.
* **Infrastructure** fields (`homelab.*`, `telemetry.*`, `trustedProjectDirs`) default to clean/off/empty, so the module evaluates to a neutral config with zero consumer input — no personal context ships in the flake.

Modules read `userConfig` via `_module.args` so nothing outside `maintainer-profile.nix` needs to import it directly. A consumer overrides values either in their own `nix-darwin` config (via `extraSpecialArgs`) or by importing the module and setting options.

### Secrets and injection

Runtime secrets (API keys, tokens, Doppler credentials) are never stored in Nix store paths or committed files. Three injection patterns are in use:

| Pattern                       | Used by                          | Mechanism                                               |
| ----------------------------- | -------------------------------- | ------------------------------------------------------- |
| Doppler subprocess wrapper    | Google Workspace MCP, Splunk MCP | `doppler run -p <project> -c prd -- <binary>`           |
| macOS Keychain via shell init | HuggingFace token, GitHub PAT    | `security find-generic-password` exported in `~/.zshrc` |
| Kubernetes Doppler Operator   | Bifrost, Cribl pods              | In-cluster operator syncs Doppler → K8s Secrets         |

The variable catalog (required vs optional, purpose, source) lives in `.env.example` at the repo root; a real `.env` is an opt-in convenience — direct injection is preferred. The local injection runbook is `AGENTS.local.md` (gitignored).

## Getting started

<Steps>
  <Step title="Try a single tool">
    `nix run github:JacobPEvans/nix-ai#claude-code -- --help`. No clone needed.
  </Step>

  <Step title="Enter the sandbox shell">
    `nix develop github:JacobPEvans/nix-ai` drops you into a shell with every AI CLI on PATH.
  </Step>

  <Step title="Import into nix-darwin">
    Add `nix-ai` as a flake input, then include `nix-ai.overlays.default` in your nixpkgs config. The README has the boilerplate.
  </Step>

  <Step title="Override the maintainer profile">
    Set `userConfig.user.fullName` and any `homelab.*` / `telemetry.*` options in your own config to adapt the stack to your environment.
  </Step>
</Steps>

## Related repos

<CardGroup cols={2}>
  <Card title="ai-assistant-instructions" icon="book" href="/ai-development/ai-assistant-instructions">
    The rules layer. nix-ai packages the tools; this configures them.
  </Card>

  <Card title="claude-code-plugins" icon="plug" href="/ai-development/claude-code-plugins">
    Extension layer on top of the packaged Claude Code CLI.
  </Card>

  <Card title="nix-darwin" icon="apple" href="/nix/nix-darwin">
    The system-level consumer.
  </Card>

  <Card title="Local LLM" icon="microchip" href="/local-llm/overview">
    How the packaged MLX stack runs and is tuned on Apple Silicon.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/JacobPEvans/nix-ai">
    Packages, overlays, full README.
  </Card>
</CardGroup>