Glossary

A

Agent An AI tool (Codex or Claude) managed by Kavi as a headless child process. Each agent operates in its own worktree.

Approval A gate that requires operator confirmation before an agent can use a specific tool. Managed via hooks for both Claude and Codex.

Approval Rule A saved decision about whether a specific tool action should be allowed, denied, or prompted. Rules can be remembered across turns.

B

Base Branch The git branch Kavi uses as the starting point for worktrees and the target for landing. Configured in .kavi/config.toml.

Base Commit The commit from which agent worktrees are created. Used as the reference point for diff tracking.

C

Claim A record of which agent has modified (or intends to modify) a specific file path. Claims are tracked to detect overlapping ownership.

Composer The inline task input in the TUI. Provides live route preview and planning mode selection.

D

DAG (Directed Acyclic Graph) The task dependency structure produced by planning mode. Tasks form a graph where dependencies must complete before dependent tasks can start.

Daemon The background process that schedules tasks, manages approvals, and streams state to the TUI via a local RPC socket.

Decision A recorded choice — routing, approval, task, or integration — stored in the decision ledger for audit purposes.

Disposition The type of review note: approve, concern, question, note, accepted_risk, or wont_fix.

E

Envelope The structured output from an agent task. Includes summary, status, blockers, peer messages, and raw output.

Event A timestamped record in the event log. Events track state changes, task lifecycle, and operator actions.

Execution Mode How a task in a plan should be scheduled: blocking (sequential), parallel (concurrent with other parallel tasks), or follow_up (after all other tasks).

F

Full-Access Mode A session mode where agents run without approval prompts. Enabled with --approve-all or the ! toggle in the TUI.

H

Hotspot A file path where multiple agents have overlapping claims. Indicates potential integration needs.

I

Integration Worktree A temporary git worktree created during kavi land to merge changes from both agent worktrees and run validation.

L

Landing The process of merging validated agent work into the target branch. Includes snapshot commits, integration merge, validation, and fast-forward.

Landing Report A JSON file persisted after each kavi land with details about the merge, validation, review threads, and change surface.

O

Operator The human user who interacts with Kavi through the TUI or CLI. The operator routes tasks, reviews diffs, approves actions, and lands work.

Ownership Rule A glob pattern in .kavi/config.toml that assigns file paths to a specific agent for routing purposes.

P

Path Claim See Claim.

Peer Message A structured message from one agent to another with an intent (question, handoff, review_request, blocked, context_share).

Planning Mode The system that decides whether a prompt should be decomposed into a DAG before execution. Modes: auto, plan, direct.

R

Recommendation A suggestion from Kavi about actions the operator should take — handoffs, integrations, or ownership config changes.

Review Thread A discussion attached to a specific diff or file change. Threads have dispositions, assignees, and status (open/resolved/landed).

S

Session A managed Kavi instance for a repository. Includes agent worktrees, the daemon, event log, and all state.

Session Record The JSON file that holds the in-memory state of the session: tasks, plans, claims, reviews, approvals, messages, and agent status.

Snapshot Commit A commit created by Kavi before landing to capture the current state of a dirty agent worktree.

T

TUI (Terminal User Interface) The full-screen operator console with 9 views, keyboard shortcuts, and real-time updates.

V

Validation Command An optional shell command (e.g., npm test) that runs in the integration worktree during kavi land.

W

Worktree An isolated git checkout for an agent. Each agent has its own worktree so changes don't interfere during execution.