Environment Variables

Kavi supports environment variables for overriding directory paths and enabling optional features. These take effect immediately without config file changes.

Available Variables

KAVI_HOME_CONFIG_DIR

Override where Kavi looks for the user-local config.toml:

export KAVI_HOME_CONFIG_DIR=/custom/config/path

With this set, Kavi reads user configuration from /custom/config/path/config.toml instead of ~/.config/kavi/config.toml.

When to Use

• Restricted environments where the XDG default (~/.config) is not available or not writable
• Containers where you mount configuration from an external volume
• CI/CD pipelines where you want to use a specific config without modifying the home directory
• Shared machines where multiple users need isolated Kavi configurations

Example: Docker Container

ENV KAVI_HOME_CONFIG_DIR=/app/config/kavi
COPY kavi-config.toml /app/config/kavi/config.toml

KAVI_HOME_STATE_DIR

Override where Kavi stores machine-local state:

export KAVI_HOME_STATE_DIR=/custom/state/path

The state directory contains:

• RPC control socket -- the Unix socket used for TUI-to-daemon communication
• Session history -- historical session metadata
• SQLite databases -- when SQLite mirroring is enabled

Changing this variable affects how the TUI connects to the daemon, so both the daemon and TUI must use the same value.

When to Use

• Non-standard filesystem layouts where ~/.local/state is not available
• Ephemeral environments where you want state on a tmpfs or ramdisk for performance
• Multi-instance setups where separate Kavi instances need isolated state

Example: Ramdisk for Performance

export KAVI_HOME_STATE_DIR=/dev/shm/kavi-state

KAVI_ENABLE_SQLITE_HISTORY

By default, Kavi logs events to a JSONL file. Enable SQLite mirroring for queryable event history:

export KAVI_ENABLE_SQLITE_HISTORY=1

Or set it for a single session:

KAVI_ENABLE_SQLITE_HISTORY=1 kavi open

What SQLite Provides

When enabled, events are written to both the JSONL file and a SQLite database:

• Queryable history -- find events by type, agent, time range, or task using SQL
• Aggregation -- compute statistics like task duration, approval rates, and routing patterns
• Faster reads -- SQLite is significantly faster than scanning large JSONL files for specific events

The SQLite database is stored at <state_dir>/history/<repo-hash>.db.

Relationship to JSONL

SQLite mirroring is additive, not a replacement:

• The JSONL file remains the source of truth
• SQLite is a secondary index that can be rebuilt from the JSONL log
• If the SQLite database is corrupted or deleted, Kavi can regenerate it from the event log

When to Enable

• Sessions that generate large volumes of events (long-running, many tasks)
• When you want to query event history programmatically
• When you need aggregated statistics about agent behavior

When to Skip

• Short sessions where JSONL scanning is fast enough
• Environments where disk space is limited (SQLite adds overhead)
• When you don't need queryable history

Setting Variables

Shell Profile

Add variables to your shell profile for persistence:

# ~/.zshrc or ~/.bashrc
export KAVI_HOME_CONFIG_DIR="$HOME/.config/kavi"
export KAVI_HOME_STATE_DIR="$HOME/.local/state/kavi"
export KAVI_ENABLE_SQLITE_HISTORY=1

Per-Session

Set variables for a single session:

KAVI_ENABLE_SQLITE_HISTORY=1 kavi open

direnv

Use direnv for per-project environment variables:

# .envrc in your project root
export KAVI_ENABLE_SQLITE_HISTORY=1

Notes

• Environment variables take effect immediately -- no config file changes needed
• The KAVI_HOME_* variables are primarily for non-standard environments (containers, CI, shared machines)
• All three variables are optional; Kavi works with sensible defaults when they are not set
• Changes to KAVI_HOME_STATE_DIR require restarting both the daemon and TUI