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 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 distinct primary purpose, but diff overlaps with build, switch, and check because it can both build and activate. check's dry-build also partially overlaps with diff's preview behavior, though the descriptions do clarify the intended use cases.
The naming is readable and all lowercase, but it mixes bare verbs (diff, build, switch, check), a noun (generations), and verb_noun pairs (eval_config, locate_option). There is no single consistent pattern across the set.
Seven tools is well-scoped for a NixOS/Home Manager agent. Each tool covers a meaningful part of the configuration lifecycle without unnecessary redundancy or bloat.
The surface covers the core workflow: build, switch, diff, validate, rollback, evaluate config values, and locate option definitions. This is a complete enough set for practical system configuration management, with no obvious dead ends.