File Layout
Directory structure reference for the .kavi/ directory and machine-local state
Repo-Local (.kavi/)
Created by kavi init in your project root.
config.toml
codex.md
claude.md
session.json
events.jsonl
events.db
approvals.json
land-001.json
task-<id>.json
.gitignore
| File | Purpose |
|---|---|
config.toml | Project configuration |
prompts/codex.md | Custom system prompt for Codex |
prompts/claude.md | Custom system prompt for Claude |
state/session.json | Current session record |
state/events.jsonl | Event log (append-only) |
state/events.db | SQLite mirror (opt-in) |
state/approvals.json | Approval rules ledger |
.gitignore | Ignores state/ from version control |
Machine-Local
Defaults to standard XDG paths. Override with environment variables.
config.toml
<repo-hash>.sock
<repo-hash>.db
Worktrees
Created by kavi open or kavi start. Location is managed by git.
Each worktree is a full checkout of the repository at the base commit, independent of the main working tree.
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
KAVI_HOME_CONFIG_DIR | ~/.config/kavi | User-local config directory |
KAVI_HOME_STATE_DIR | ~/.local/state/kavi | Machine-local state directory |
KAVI_ENABLE_SQLITE_HISTORY | 0 | Set to 1 to enable SQLite event mirroring |