A command-line tool that provides AI-powered assistance for NixOS configuration, troubleshooting, and system management. nixai helps both newcomers and experts work more efficiently with NixOS through intelligent automation and guidance.
Run directly without installation:
# Ask a question
nix run github:olafkfreund/nix-ai-help -- ask "how do I configure nginx?"
# Launch interactive interface
nix run github:olafkfreund/nix-ai-help -- tui
# Analyze your system
nix run github:olafkfreund/nix-ai-help -- doctor- Natural Language Queries: Ask questions in plain English about NixOS configuration and troubleshooting
- Context-Aware Responses: Automatically detects your system configuration (flakes vs channels, Home Manager, services)
- Multiple AI Providers: Supports local Ollama, OpenAI, Claude, Gemini, Groq, and other providers
- Privacy-First: Defaults to local inference with Ollama
- Hardware Detection: Comprehensive hardware analysis and optimization recommendations
- Configuration Generation: Generate NixOS configurations from natural language descriptions
- Diagnostics: AI-powered analysis of system logs and build failures
- Health Monitoring: System health checks and performance monitoring
- Package Analysis: Analyze Git repositories and generate Nix derivations automatically
- Build Troubleshooting: Intelligent build failure analysis with suggested fixes
- Development Environments: Create and manage project-specific development shells
- Editor Integration: VS Code and Neovim integration via Model Context Protocol (MCP)
- Fleet Management: Multi-machine deployment and monitoring
- Template System: Reusable configuration templates for common setups
- Plugin Architecture: Extensible plugin system with secure sandboxing
- Web Interface: Modern dashboard for visual configuration management
# Run latest version directly
nix run github:olafkfreund/nix-ai-help
# Or install permanently
nix profile install github:olafkfreund/nix-ai-helpgit clone https://github.com/olafkfreund/nix-ai-help.git
cd nix-ai-help
nix build
./result/bin/nixai --helpAdd to your configuration.nix or home.nix:
{ config, pkgs, ... }:
let
nixai = pkgs.callPackage (builtins.fetchGit {
url = "https://github.com/olafkfreund/nix-ai-help.git";
ref = "main";
} + "/package.nix") {};
in {
environment.systemPackages = [ nixai ]; # For NixOS
# OR
home.packages = [ nixai ]; # For Home Manager
}nixai ask "How do I enable SSH in NixOS?"
nixai ask "Debug my failing build"
nixai tui # Interactive interfacenixai doctor # System health check
nixai hardware detect # Hardware analysis
nixai context show # View system context
nixai diagnose /var/log/nixos-rebuild.lognixai configure # Interactive configuration wizard
nixai configure --template desktop
nixai migrate channels-to-flakes
nixai templates listnixai package-repo https://github.com/user/project
nixai build debug # Analyze build failures
nixai flake init # Initialize new flake
nixai devenv create python # Development environmentnixai provider list # Show available AI providers
nixai provider models --provider ollama
nixai provider test --provider ollama --model llama3
nixai provider config # Configuration helpnixai supports multiple AI providers for different use cases:
- Ollama: Local inference with models like llama3, deepseek-r1, mistral
- LlamaCpp: CPU-optimized local inference
- OpenAI: GPT-4, GPT-3.5-turbo (best accuracy for NixOS tasks)
- Claude: Claude Sonnet 4, Claude 3.7 (excellent reasoning)
- Gemini: Gemini 2.5 Pro (strong capabilities)
- Groq: Ultra-fast inference with Llama models
- GitHub Copilot: Integrated with development workflows
Set your preferred provider in ~/.config/nixai/config.yaml:
ai_provider: ollama
ai_model: llama3
# Or use environment variables
# export OPENAI_API_KEY="your-key"
# export CLAUDE_API_KEY="your-key"For detailed provider setup, run: nixai provider config
- User Manual: Complete command reference and examples
- Installation Guide: Detailed installation instructions
- VS Code Integration: Editor integration setup
- Hardware Guide: Hardware detection and optimization
- Community Resources: Community support and guides
- Nix with flakes enabled
- Go 1.21+ (managed via Nix)
- just (for development tasks)
git clone https://github.com/olafkfreund/nix-ai-help.git
cd nix-ai-help
nix develop # Enter development shell
just build # Build nixai
just test # Run tests
./nixai --help- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Update documentation
- Submit a pull request
nixai follows clean architecture principles with modular components:
- CLI Layer: Command-line interface and command implementations
- AI Layer: Multi-provider AI integration with specialized agents
- Core Layer: NixOS-specific logic and system integration
- Infrastructure: Logging, configuration, error handling
Key features:
- 40+ specialized commands for NixOS management
- Context-aware AI responses based on system configuration
- Plugin system with secure sandboxing
- Multi-provider AI support with automatic fallback
- Clean separation of concerns for maintainability
Build failures: Ensure Nix version 2.4+ with flakes enabled
nix --version # Should be 2.4+
nix build --rebuildAI provider errors: Check provider configuration
nixai provider list # Check provider status
nixai provider test # Test your configurationOllama 404 errors: Verify model availability
nixai provider models --provider ollama
# Pull missing models: ollama pull llama3For more help:
- Run
nixai doctorfor system diagnostics - Check the troubleshooting guide
- Use
nixai communityfor support channels
This project is open source. See the repository for license details.
We welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or sharing configuration templates, your help makes nixai better for everyone.
For development guidelines and contribution instructions, see the User Manual.