Configuration
An overview of how to configure Kavi with project-level and user-level TOML files, custom prompts, routing rules, and environment variables.
Configuration
Kavi uses a layered configuration system with project-level and user-level settings. Configuration is written in TOML and covers routing, agent behavior, validation, and runtime settings.
Configuration Layers
Kavi reads configuration from multiple sources, with more specific sources overriding more general ones:
- Built-in defaults -- sensible defaults for all settings
- User-level config --
~/.config/kavi/config.tomlfor personal preferences and binary paths - Project-level config --
.kavi/config.tomlfor project-specific routing, agents, and validation - Environment variables -- override specific paths and feature flags
- CLI flags -- runtime overrides like
--approve-all
Both project and user configs are created by kavi init. Project config is created always; user config requires the --home flag.
Quick Reference
| Setting | Location | Purpose |
|---|---|---|
| Project config | .kavi/config.toml | Routing rules, agents, validation |
| User config | ~/.config/kavi/config.toml | Binary paths, personal preferences |
| Custom prompts | .kavi/prompts/ | Per-agent system prompts |
| Routing rules | .kavi/config.toml [routing] | Path ownership, keywords |
| Environment variables | Shell environment | Directory overrides, feature flags |
Getting Started
The minimal configuration to get started with Kavi is a project-level config file:
# .kavi/config.toml
version = 1
base_branch = "main"This tells Kavi which branch to use as the base for agent worktrees and landing. All other settings use built-in defaults.
For a more complete setup, add routing rules and a validation command:
version = 1
base_branch = "main"
validation_command = "npm test"
[routing]
codex_paths = ["src/backend/**", "src/lib/**"]
claude_paths = ["src/components/**", "src/pages/**"]See each configuration page for detailed reference and examples.