Architecture

Kavi follows a daemon + TUI architecture where the long-running daemon manages agent processes and state while the TUI provides the operator interface.

System Overview

┌─────────────────────────────────────────────────┐
│                    Operator                      │
│                   (you, in Ghostty)              │
└──────────────────────┬──────────────────────────┘
                       │
              ┌────────▼────────┐
              │    Kavi TUI     │
              │  (Ink 6.x/React)│
              └────────┬────────┘
                       │ Unix Socket
              ┌────────▼────────┐
              │   Kavi Daemon   │
              │  (background)   │
              └───┬─────────┬───┘
                  │         │
         ┌────────▼──┐  ┌──▼────────┐
         │ Claude CLI │  │ Codex CLI │
         │ (headless) │  │ (headless)│
         └────────────┘  └───────────┘

The Daemon

The Kavi daemon is a background process that handles:

• Agent lifecycle management -- spawning, monitoring, and terminating Claude and Codex CLI processes
• Task scheduling -- determining execution order from DAG dependencies
• Claim tracking -- recording which agent owns which files and paths
• Approval processing -- intercepting tool calls and enforcing approval rules
• Recommendation generation -- analyzing agent activity and surfacing actionable suggestions
• Event persistence -- writing all events to the JSONL log and optional SQLite store

The daemon starts automatically when you launch a Kavi session and shuts down when the session ends.

RPC Communication

The TUI communicates with the daemon over a Unix domain socket. This decouples the rendering layer from the orchestration logic, allowing the daemon to continue managing agents even if the TUI disconnects momentarily.

Messages between the TUI and daemon are structured JSON-RPC calls covering operations like:

• Starting and stopping tasks
• Submitting approval decisions
• Requesting plan modifications
• Querying session state

Agent IPC

Kavi spawns agents as headless child processes with structured I/O:

Claude Code CLI:

claude -p --input-format stream-json --output-format stream-json --bare --session-id <uuid>

Claude runs in streaming JSON mode with a persistent session ID, enabling multi-turn conversations within a single task.

codex exec --json --sandbox workspace-write --ephemeral

codex app-server --listen stdio://

Session Model

A session represents a complete unit of work in Kavi. Each session has:

• A unique session ID (ULID)
• A session record (JSON) storing metadata and current state
• An event log (JSONL) capturing every action, decision, and state change
• Task artifacts produced by agents
• Landing reports from completed integrations

Sessions persist across TUI restarts. You can reconnect to an existing session and resume where you left off.

TUI

The TUI is built with Ink 6.x (React for terminals) and renders in your terminal emulator. It provides:

• Task panels showing agent output streams in real time
• Approval inbox for pending tool-call approvals
• Plan view displaying the current execution DAG
• Review threads for examining diffs and dispositions
• Recommendation feed with actionable suggestions
• Peer message display showing inter-agent communication

The TUI is a presentation layer -- all orchestration logic lives in the daemon.