AI-powered CLI assistant for NixOS configuration, troubleshooting, and documentation queries. Supports multiple LLM providers with local-first privacy approach.
You are an AI assistant for the nixai project, a modular console-based Linux application that provides AI-powered help for NixOS configuration and troubleshooting.
nixai is a Go-based CLI tool that:
1. **Entry Point**: `cmd/nixai/main.go` - main application entry
2. **CLI Logic**: `internal/cli` - all command implementations and submodules
3. **AI Integration**: `internal/ai` - LLM provider implementations
4. **MCP Server**: `internal/mcp` - documentation query system
5. **NixOS Tools**: `internal/nixos` - log parsing, diagnostics, command execution
6. **Configuration**: `internal/config` - YAML config management (`configs/default.yaml`)
7. **Logging**: `pkg/logger` - structured logging with configurable levels
8. **Utilities**: `pkg/utils` - file checks, string helpers, formatting
1. **Idiomatic Go**: Write clean, idiomatic Go code with proper error handling
2. **Modularity**: Each feature should be a separate, testable module
3. **Privacy First**: Default to local Ollama inference; use cloud LLMs only when specified
4. **Configuration-Driven**: All settings loaded from YAML via `internal/config`
5. **Testability**: All new features must include tests
6. **Documentation**: Update README.md and docs/MANUAL.md for all changes
All AI providers in `internal/ai` must implement:
```go
type Provider interface {
Query(ctx context.Context, question string) (string, error)
GenerateResponse(ctx context.Context, prompt string) (string, error)
}
```
1. **Default Provider**: Ollama with `llama3` model (privacy-focused, local)
2. **User Selection**: Allow runtime provider selection via config or flags
3. **Fallback Logic**: Gracefully handle provider unavailability
4. **API Keys**: Store in environment variables, never in config files
5. **Prompt Formatting**: Maintain consistent prompt structure across providers
6. **Direct Questions**: Use `Query` method for `nixai "question"` interface
Support both formats:
Always use the provider's `Query` method for direct questions.
Query NixOS documentation from these sources via MCP server (`internal/mcp`):
Handle MCP server unavailability gracefully with clear error messages.
1. Accept input via:
- File path argument
- Piped input (stdin)
- Direct command execution
2. Parse using `internal/nixos` package
3. Analyze with LLM provider
4. Return actionable diagnostics
Each submodule should have:
**Supported Submodules**:
Use utilities from `pkg/utils`:
```go
utils.FormatHeader("Section Title")
utils.FormatKeyValue("Key", "Value")
utils.FormatDivider()
```
Use `glamour` for Markdown output with syntax highlighting.
Show progress for:
All commands must provide:
Use the `justfile` for common tasks:
Use `flake.nix` for:
1. Add tests for all new features
2. Update existing tests when modifying functionality
3. Ensure test coverage for error cases
4. Test with multiple AI providers
1. **Sanitize User Input**: Validate and sanitize all user-provided data
2. **Log Parsing**: Handle malformed logs gracefully
3. **Command Execution**: Validate NixOS commands before execution
4. **API Keys**: Never log or expose API keys
5. **Error Handling**: Use idiomatic Go error handling with context
Update for all changes:
Include examples for:
When answering questions about frameworks, libraries, or APIs, use Context7 to retrieve current documentation rather than relying on training data. This ensures responses use the latest information.
1. **Context Propagation**: Pass context through all async operations
2. **Graceful Degradation**: Provide fallbacks when services unavailable
3. **User-Friendly Messages**: Translate technical errors into actionable guidance
4. **Logging**: Log errors at appropriate levels using `pkg/logger`
1. Keep code modular, well-documented, and testable
2. Prefer local Ollama for privacy; support cloud LLMs as option
3. Validate and sanitize all inputs
4. Format terminal output consistently with utilities
5. Provide clear help menus with practical examples
6. Handle piped input and file arguments seamlessly
7. Show progress for long-running operations
8. Update tests and documentation with all changes
9. Use Nix for reproducible builds and development
10. Keep all `.instructions.md` files up to date
When implementing new features or fixing bugs:
1. Follow the architecture guidelines above
2. Add or update tests for all code changes
3. Update relevant documentation
4. Ensure help menus reflect new functionality
5. Test with multiple AI providers
6. Validate input handling and error cases
7. Run `just lint` and `just test` before committing
8. Update submodule `.instructions.md` if applicable
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/nixai-ai-powered-nixos-help-system/raw