Core Concepts
An overview of the fundamental concepts behind Kavi's multi-agent orchestration architecture.
Core Concepts
Kavi is a TUI-based multi-agent orchestrator that coordinates Claude Code CLI and Codex CLI as headless child processes. Rather than interacting with each agent directly, you interact with Kavi, which routes tasks, manages execution, and handles coordination between agents.
This section covers the foundational concepts you need to understand how Kavi works.
Architecture
Kavi runs a background daemon that communicates with the TUI over a Unix socket. The daemon manages agent lifecycles, schedules tasks, tracks claims, and generates recommendations. Sessions encapsulate a complete unit of work and persist across restarts.
Read more about the architecture
Routing
Every task must be assigned to an agent. Kavi uses a layered routing strategy: path ownership rules first, then keyword heuristics, then an AI-powered fallback via Codex. Each route decision produces a confidence score and is recorded in a decision ledger.
Planning
Kavi can decompose complex work into execution graphs (DAGs) with dependency tracking and multiple execution modes. Plans move through a lifecycle from draft to active to completed or blocked.
Worktrees
Each agent operates in its own git worktree, providing full isolation. Agents commit independently, and integration happens through a transient worktree where changes are merged and validated before landing.
Reviews
Kavi supports diff-based review threads with structured dispositions. Reviews can be assigned to agents or the operator, and follow-up tasks can be created directly from review comments.
Approvals
An approval gateway intercepts tool calls from agents. Per-tool rules determine whether a call is allowed, denied, or requires operator approval. Decisions can be remembered for the session.
Recommendations
Kavi generates actionable recommendations for handoffs, integration points, and ownership configuration. Recommendations are deduplicated by fingerprint and support a dismiss/restore lifecycle.
Read more about recommendations
Landing Workflow
Landing brings agent work into your target branch. Kavi snapshots dirty worktrees, merges in an integration worktree, runs your validation command, and fast-forwards the target branch on success.
Read more about the landing workflow
Peer Messaging
Agents can exchange structured messages with intents like question, handoff, review request, blocked, and context share. Messages are visible in the TUI and are fed into the receiving agent's next prompt.
Read more about peer messaging
State and Persistence
Kavi persists all session data under .kavi/ in your project root. Events are logged to JSONL with optional SQLite backing. Task artifacts, landing reports, and approval rules are all persisted.