nix-agent
<p align="center">
<img src="assets/banner.png" alt="nix-agent: composable NixOS and Home Manager operations for AI agents" width="100%">
</p>
A local MCP server that gives AI agents composable NixOS / Home Manager
operations: build, diff, switch, and generations for the operational core,
plus eval, locate, and check for config introspection.
It pairs with [`mcp-nixos`](https://github.com/utensils/mcp-nixos). nix-agent
operates on your actual configuration, `mcp-nixos` handles package and option
discovery. Optional local usage logging (`NIX_AGENT_USAGE_LOG=1`) records
per-call byte accounting; run `nix-agent usage` to summarize.
The documented default is high trust: unprompted `switch` / `generations`
and passwordless sudo narrowed to this machine's flake. Lower trust (host
prompts, a sudo password) is an opt-down.
> **Experimental and a work in progress.** Feedback and contributions welcome.
## Install
Paste this to a coding agent (Codex, Claude Code, opencode, ...) and it does the install:
```
Read https://raw.githubusercontent.com/JEFF7712/nix-agent/main/docs/agent-install.md and follow every step to install nix-agent on this NixOS system, install the companion skills, and register nix-agent in my MCP settings for this machine.
```
Or do it by hand, see [docs/usage.md](docs/usage.md#install).
## Docs
- [docs/usage.md](docs/usage.md): install, MCP host config, tool surface, workflow, design notes
- [docs/agent-install.md](docs/agent-install.md): high-trust install guide for agents
- [docs/privileged-automation.md](docs/privileged-automation.md): default non-interactive dry-activate, switch, and rollback (opt-down for a sudo password)
- [skills/nix-agent/SKILL.md](skills/nix-agent/SKILL.md): companion workflow skill
- [skills/nix-agent-init/SKILL.md](skills/nix-agent-init/SKILL.md): repo onboarding skill
The published documentation pages are generated directly from these Markdown files.
---
The nix-agent logo adapts the Nix snowflake from [NixOS/nixos-artwork](https://github.com/NixOS/nixos-artwork), licensed [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/).
TDQS
Scored across 7 tools
Each tool has a mostly distinct role in the Nix lifecycle: build, check, diff, switch, rollback/list generations, eval_config, and locate_option. Some overlap exists around building/validating closures (build vs. check dry-build vs. diff), but the descriptions clarify when each should be used.
Names are all lowercase snake_case and mostly action-oriented verbs, with multi-word tools following a verb_noun pattern. The main deviation is 'generations', a noun, but the overall convention is predictable and readable.
Seven tools is well-scoped for a Nix deployment agent. Each tool covers a meaningful operation, and there is no obvious filler or redundant surface.
The surface covers the core lifecycle: validation, build, diff, activation, rollback, generation listing, config evaluation, and option location. Direct config file editing/search is not included, but locate_option plus external discovery/editing tools make that a minor gap rather than a dead end.