The whole AI toolkit, in one flake. nix run and go.
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-darwinandnix-homecan 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 overlay, User environment packages, ad-hoc nix shell | ai-assistant-instructions rule set |
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.
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 |
.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
Enter the sandbox shell
nix develop github:JacobPEvans/nix-ai drops you into a shell with every AI CLI on PATH.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.Related repos
ai-assistant-instructions
The rules layer. nix-ai packages the tools; this configures them.
claude-code-plugins
Extension layer on top of the packaged Claude Code CLI.
nix-darwin
The system-level consumer.
Local LLM
How the packaged MLX stack runs and is tuned on Apple Silicon.
Source on GitHub
Packages, overlays, full README.