NixOS AI Helper - Copilot Instructions
This skill provides comprehensive guidance for developing **nixai**, a modular console-based Linux application that assists with NixOS configuration, troubleshooting, and setup directly from the command line using AI-powered help.
Project Overview
**nixai** is a Go-based CLI tool that:
Answers NixOS questions via `nixai "question"` or `nixai --ask "question"`Integrates multiple LLMs (Ollama, Gemini, OpenAI) with local-first privacy defaultsQueries NixOS documentation through an MCP server from official and community sourcesParses logs, diagnoses issues, and executes NixOS commandsProvides modular subcommands for community, packaging, learning, devenv, neovim, and machinesArchitecture Constraints
Configuration Management
All configuration loaded from YAML (`configs/default.yaml`) via `internal/config` packageAPI keys stored in environment variables only, never in config filesUser-selectable AI providers with fallback supportCode Organization
**`cmd/nixai/main.go`**: Main entrypoint**`internal/ai`**: All LLM interactions (providers must implement both `Query` and `GenerateResponse`)**`internal/mcp`**: Documentation queries using config-defined sources**`internal/nixos`**: Log parsing, diagnostics, NixOS command execution**`internal/cli`**: All CLI commands and submodule logic**`pkg/logger`**: Logging respecting config log levels**`pkg/utils`**: Utility functions (file checks, string helpers, formatting)AI Provider Requirements
All providers must implement `Query` and `GenerateResponse` methodsDefault to Ollama with `llama3` model for privacyConsistent prompt formatting across providersGraceful fallback when providers unavailableKey Features Implementation
1. Direct Question Assistant
```bash
nixai "How do I enable Docker?"
nixai --ask "Explain flakes"
nixai -a "Debug boot failure"
```
Use provider's `Query` method for direct questionsFormat responses with Markdown rendering via `glamour`2. Documentation Integration
Query NixOS documentation from:
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/Handle MCP server unavailability gracefully.
3. Log & Config Diagnostics
Accept piped input: `journalctl -xe | nixai diagnose`Parse and analyze NixOS logs using LLMsExecute local NixOS commands and diagnose output4. Specialized Commands
**`package-repo`**: Analyze Git repos and generate Nix derivations**`explain-option`**: Explain NixOS options**`explain-home-option`**: Explain Home Manager options**Modular subcommands**: community, learning, devenv, machines, neovim (each with own instructions)Coding Standards
Idiomatic Go Practices
Use modular design with clear separation of concernsImplement proper error handling with contextValidate and sanitize all user/log inputWrite testable, well-documented codeTerminal UI Guidelines
Use `pkg/utils` formatting helpers:
`utils.FormatHeader()` for section headers`utils.FormatKeyValue()` for key-value pairs`utils.FormatDivider()` for visual separation`glamour` for Markdown rendering with syntax highlightingShow progress indicators for API calls and long operationsCLI Help Menus
All commands must provide:
Clear, formatted help textUsage examplesFlag descriptionsActionable guidanceTesting & Build Process
Development Workflow
Use `justfile` for build, test, lint, and run tasksUse Nix (`flake.nix`) for reproducible builds and dev environmentsAll new features require corresponding testsUpdate tests when fixing bugsQuality Requirements
Test coverage for all new featuresValidation of edge cases and error conditionsIntegration tests for AI provider interactionsDocumentation updates in sync with code changesDocumentation Requirements
Keep Updated
**`README.md`**: User-facing documentation with examples**`docs/MANUAL.md`**: Comprehensive manual for all features**This instruction file**: Overall project guidelines**Submodule `.instructions.md`**: Module-specific Copilot instructionsDocument Both Interfaces
Provide examples for:
Direct question mode: `nixai "question"`Flag-based mode: `nixai --ask "question"`Piped input: `command | nixai diagnose`All subcommands with realistic use casesBest Practices
1. **Privacy First**: Default to local Ollama inference, fallback to cloud LLMs only when needed
2. **Modular Design**: Each feature area has its own submodule with dedicated instructions
3. **Error Handling**: Use idiomatic Go error handling with context throughout
4. **User Experience**: Show progress, format output clearly, provide actionable help
5. **Documentation Queries**: Always use Context7 to retrieve current framework/library documentation rather than relying on training data
6. **Maintainability**: Keep code well-documented, testable, and consistent with project conventions
When Implementing New Features
1. Ensure feature fits within existing module structure
2. Add/update tests for new functionality
3. Update help menus and documentation
4. Validate against coding guidelines
5. Test with multiple AI providers
6. Update relevant `.instructions.md` files
7. Verify integration with existing workflows
Integration Points
**MCP Server**: Document availability checks and error handling**AI Providers**: Ensure consistent interface implementation**NixOS Commands**: Validate command execution and output parsing**Config System**: Respect user preferences from YAML config**Logging**: Use configured log levels appropriately---
Use these instructions to maintain consistency, ensure feature completeness, and preserve the modular architecture of the nixai project. When contributing or extending functionality, always reference current documentation via Context7 for frameworks and APIs.