Initialization

Before starting a session, Kavi needs configuration files that tell it how to behave in your project and (optionally) across all your projects. The kavi init command creates these for you.

Project Initialization

Navigate to your git repository and run:

cd your-project
kavi init

This creates a .kavi/ directory in the repository root with the following structure:

.kavi/
  config.toml    # Project-specific configuration
  state/         # Session state, event logs, task history

The .kavi/config.toml file contains project-level settings such as routing rules, agent preferences, and approval policies. These settings apply only to this repository.

What Goes in .kavi/config.toml

A freshly generated project config includes sensible defaults. Key sections:

[routing]
# Path-based routing rules
# Example: route frontend files to Claude, backend to Codex

[agents.claude]
# Claude-specific settings

[agents.codex]
# Codex-specific settings

[approval]
# Tool-call approval policy

You can edit this file at any time. See the Configuration docs for the full reference.

User-Level Initialization

To also create a user-level configuration file that applies across all your projects, pass the --home flag:

kavi init --home

This creates a config file at:

~/.config/kavi/config.toml

User-level settings act as defaults. Project-level settings in .kavi/config.toml override them when both exist.

When to Use --home

Use --home when you want to set preferences that apply everywhere, such as:

• Your default agent preferences (e.g., always prefer Codex for planning)
• Global approval policies
• Default routing fallbacks

For project-specific routing rules or agent configurations, use the repo-local .kavi/config.toml instead.

Configuration Precedence

When both configuration files exist, Kavi merges them with the following priority:

1. Project config (.kavi/config.toml) -- highest priority
2. User config (~/.config/kavi/config.toml) -- fallback defaults

Project-level values always win when there is a conflict.

The State Directory

The .kavi/state/ directory is created automatically when you start your first session. It stores:

• Session data -- active and historical session records
• Event logs -- JSONL event streams for each session
• Task history -- subtask graphs, routing decisions, and outcomes

You generally do not need to touch this directory.

Next Steps