Sókrates Wiki

Nix Plugin for Claude Code

2 min read

Nix Plugin for Claude Code

Summary

A specialized Claude Code plugin providing deep technical expertise for the Nix ecosystem, including the Nix CLI, NixOS module system, and Nixpkgs. It is designed to assist in the development and maintenance of the Sokrates project’s NixOS-based appliance stack by enforcing modern patterns and flake-based workflows.

Details

The Nix Plugin for Claude Code was developed to provide a reliable, up-to-date reference for Nix operations within the Sokrates project. Modeled after the Astral toolkit plugin, it uses a structured manifest system (plugin.json) and a set of specialized “skills” to guide the AI assistant in generating correct Nix code and system configurations. The plugin was synthesized from a comprehensive 2025-era research report to ensure it prioritizes modern Nix features over legacy patterns found in older documentation.

Plugin Structure

The plugin is located at plugin/nix/ and is registered via a project-level marketplace manifest at plugin/.claude-plugin/marketplace.json. It consists of three core skills:

  1. nix: This skill covers the modern Nix 3 CLI and Flakes. It includes command references for nix build, nix develop, nix flake, and nix profile. It provides guidance on flake architecture (flake.nix schema, inputs/outputs), lockfile management, and the migration path from legacy nix-shell to nix develop.
  2. nixos: This skill focuses on the NixOS module system. It details the anatomy of a module ({ config, lib, pkgs, ... }), option declaration types, and the priority engine (e.g., lib.mkForce, lib.mkDefault, lib.mkIf). It includes specific patterns for systemd services, tmpfiles, networking (nftables), and declarative disk partitioning via disko.
  3. nixpkgs: This skill provides expertise in package creation and customization. It covers stdenv.mkDerivation phases, modern overlay syntax (final: prev:), and language-specific builders for Python (buildPythonPackage), Go (buildGoModule), and Node.js. It also documents the “fake hash” workflow for updating SRI hashes in fetchers.

Integration with Sokrates

The plugin serves as the foundational knowledge base for the Hermes-NixOS Expert Agent (.claude/agents/hermes-nixos-expert.md). While the agent handles autonomous configuration changes for the Hermes Agent deployment on NixOS, the Nix Plugin provides the low-level technical constraints and syntax requirements for the broader Nix ecosystem.

Key technical decisions reflected in the plugin include:

  • Flake-First: All examples and commands default to flake-based workflows.
  • Security Boundaries: Documentation of NixOS service hardening and the separation of Hermes communication credentials from intelligence secrets.
  • Modern Syntax: Use of finalAttrs: in derivations and final: prev: in overlays to match current Nixpkgs best practices.

Graph View

Backlinks