NixOS AI Assistant Development

Instructions for building and maintaining nixai, a modular console-based Linux application for solving NixOS configuration problems and providing AI-powered assistance from the command line.

Project Architecture

nixai is a Go-based CLI tool that:

Code Organization

**Configuration**: All configuration loaded from YAML (`configs/default.yaml`) via `internal/config` package

**Core Modules**:

Coding Guidelines

1. **Use idiomatic Go** with modular design for all code

2. **Configuration**: Load from YAML via `internal/config` package

3. **AI Providers**: All providers must implement both `Query` and `GenerateResponse` methods

4. **Allow user/provider selection** with fallback mechanisms

5. **Use dedicated packages**: Don't bypass `internal/ai`, `internal/mcp`, `internal/nixos`, `pkg/logger`, or `pkg/utils`

6. **All new features must be testable and documented**

7. **Validate and sanitize** all user/log input

8. **Use context** and idiomatic error handling throughout

Key Features to Support

Direct Question Assistant

Answer questions via `nixai "question"` or `--ask`/`-a` flag using the provider's `Query` method.

Log & Config Diagnostics

Diagnose NixOS issues from logs, configs, or piped input using LLMs.

Documentation Query

Query NixOS documentation from multiple official and community sources:

NixOS Command Execution

Run and parse local NixOS commands for diagnostics.

AI Provider Selection

User can select/configure AI provider (Ollama, Gemini, OpenAI, etc.) with fallback.

Specialized Commands

CLI Features

AI Provider Integration

1. **All providers** (Ollama, Gemini, OpenAI, etc.) must implement both `Query` and `GenerateResponse` methods

2. **Default to Ollama** with `llama3` model if not specified (privacy-first)

3. **Format prompts consistently** across providers

4. **API keys** must be kept in environment variables, never in config files

5. **Gracefully handle** MCP server unavailability

Terminal UI Best Practices

1. Use `utils.FormatHeader`, `utils.FormatKeyValue`, `utils.FormatDivider` for all output

2. Use `glamour` for Markdown rendering with syntax highlighting

3. Show progress indicators for API calls and long-running operations

4. All CLI commands must provide clear, actionable help menus with usage examples

Testing & Build

1. Use the `justfile` for build, test, lint, and run tasks

2. Use Nix (`flake.nix`) for reproducible builds and dev environments

3. All features must be covered by tests; update or add tests as needed

4. Add or update tests for all new features and bugfixes

Documentation Requirements

1. Update `README.md` and `docs/MANUAL.md` for all new features, commands, and changes

2. Keep this instruction file and all submodule `.instructions.md` files up to date

3. Document both direct question and flag-based interfaces with examples

4. Each submodule should have its own Copilot instructions reflecting its responsibilities

Implementation Checklist

When adding new features:

Context Retrieval

When answering questions about frameworks, libraries, or APIs, use Context7 to retrieve current documentation rather than relying on training data.