NixOS AI Helper Development Guide
This skill guides development of nixai, a modular console-based Linux application for solving NixOS configuration problems and assisting with NixOS setup and troubleshooting from the command line.
Project Overview
nixai is a Go-based CLI tool that:
Provides direct AI-powered help via `nixai "question"` or `nixai --ask "question"`Integrates multiple LLMs (Ollama, Gemini, OpenAI) with local Ollama as privacy-focused defaultQueries NixOS documentation through an MCP server from official and community sourcesParses logs, accepts piped input, executes NixOS commands, and diagnoses issuesOffers modular submodules for community, packaging, learning, devenv, neovim, machines, and moreCoding Standards
Architecture Principles
Write idiomatic Go with modular design patternsLoad all configuration from YAML (`configs/default.yaml`) via `internal/config` packageKeep API keys in environment variables, never in config filesMaintain clear separation of concerns across packagesPackage Structure
**`internal/ai`**: All LLM interactions. Every provider must implement both `Query` and `GenerateResponse` methods. Support user provider selection and fallback logic.**`internal/mcp`**: Documentation queries using sources from config**`internal/nixos`**: Log parsing, diagnostics, and NixOS command execution**`pkg/logger`**: Centralized logging respecting config log level**`pkg/utils`**: Utility functions (file checks, string helpers, formatting)**`internal/cli`**: All CLI commands and logic. Each submodule may have its own Copilot instructions.**`cmd/nixai/main.go`**: Main entrypointCode Quality
All new features must be testable and documentedUse context and idiomatic error handling throughoutValidate and sanitize all user/log inputAdd or update tests for all new features and bugfixesCore Features
Direct Question Assistant
Answer questions via `nixai "question"` or `--ask`/`-a` flagUse the provider's `Query` method for all direct questionsFormat prompts consistently across providersLog & Config Diagnostics
Diagnose NixOS issues from logs, configs, or piped input using LLMsAccept logs/configs via pipe or file for analysisDocumentation Query
Query NixOS documentation from these sources via MCP server:
https://wiki.nixos.org/wiki/NixOS_Wikihttps://nix.dev/manual/nixhttps://nix.dev/https://nixos.org/manual/nixpkgs/stable/https://nix.dev/manual/nix/2.28/language/https://nix-community.github.io/home-manager/NixOS Command Execution
Run and parse local NixOS commandsExecute diagnostics and capture outputAI Provider Management
Support multiple LLM providers (Ollama, Gemini, OpenAI, etc.)Default to local Ollama with `llama3` model if not specifiedAllow user selection and configuration of providersAll providers must implement both `Query` and `GenerateResponse` methodsSpecialized Commands
**Package Repository Analysis**: `package-repo` command to analyze Git repos and generate Nix derivations**NixOS Option Explainer**: `explain-option` command for NixOS options**Home Manager Option Support**: `explain-home-option` command for Home Manager options**Modular Submodules**: Community, Learning, Devenv, Machines, Neovim commands with dedicated help menus and instructionsTerminal UI Standards
Output Formatting
Use `utils.FormatHeader` for section headersUse `utils.FormatKeyValue` for key-value pairsUse `utils.FormatDivider` for visual separationRender Markdown with `glamour` including syntax highlightingShow progress indicators for API calls and long-running operationsHelp Menus
All commands must provide clear, formatted, actionable help menusInclude usage examples in all help textDocument both direct question and flag-based interfacesTesting & Build
Development Workflow
Use `justfile` for build, test, lint, and run tasksUse Nix (`flake.nix`) for reproducible builds and dev environmentsEnsure all features are covered by testsTest Requirements
Update or add tests for all new features and bugfixesValidate error handling and edge casesTest provider fallback mechanismsDocumentation Standards
Required Documentation Updates
Update `README.md` for all new features, commands, and changesUpdate `docs/MANUAL.md` with detailed usage instructionsKeep this instruction file and all submodule `.instructions.md` files currentDocument both direct question and flag-based interfaces with examplesSubmodule Documentation
Each submodule should have its own Copilot instructionsDocument responsibilities and integration pointsMaintain consistency with project-wide standardsBest Practices
Privacy & Security
Prefer local inference (Ollama) for privacyFallback to cloud LLMs only when neededNever expose API keys in config files or logsReliability
Gracefully handle MCP server unavailabilityImplement robust error handling with user-friendly messagesValidate all inputs before processingMaintainability
Keep code modular, well-documented, and testableUse consistent formatting and naming conventionsUpdate all relevant documentation when adding featuresContext Retrieval
When answering questions about frameworks, libraries, or APIs, use Context7 to retrieve current documentation rather than relying on training data. This ensures accuracy and currency of information.