Configuration Overview
Nia’s configuration system provides a flexible, hierarchical approach to customizing behavior across projects and teams. Configuration files control AI agent selection, development tool integration, project metadata, and workflow customization.
Configuration Files
Nia uses TOML-based configuration files stored in .nia/config/:
| File | Purpose | Location |
|---|---|---|
project.toml | Project metadata and settings | .nia/config/project.toml |
agents.toml | AI agent selection and model configuration | .nia/config/agents.toml |
toolchain.toml | Development tools (issue trackers, code platforms) | .nia/config/toolchain.toml |
commands.toml | Workflow command customizations | .nia/config/commands.toml |
Quick Links
- Configuration Files Reference - Quick reference for all config files
- Project Configuration - Configure project metadata
- Context Sources - Add context files to AI prompts
- Commit Behavior - Control commit generation
- Toolchain Configuration - Configure development tools
- Hierarchical Loading - Multi-source configuration
- Agent Skills - Customizable procedural knowledge
Getting Started
- Initialize configuration:
nia config init - Edit
.nia/config/project.tomlwith project metadata - Configure your toolchain in
.nia/config/toolchain.toml - Validate configuration:
nia config validate
Configuration Hierarchy
Nia loads configuration from multiple locations (highest priority first):
- Repository (
.nia/config/) - Application (multi-repo scenarios)
- User (
~/.config/nia/) - System (
/etc/nia/)
Settings from higher-priority sources override those from lower-priority sources. By default, only repository configuration is loaded; external sources must be explicitly enabled in project.toml for security reasons.
See Hierarchical Loading for details on multi-source configuration.