Mandip Adhikari
← Index
ProjectApr 2026

Kavi

A daemon plus terminal UI that runs Claude Code and Codex as headless child processes, each in its own git worktree. It routes tasks between them, gates their tool calls through approvals, and merges their branches back with overlap detection.

npm install -g @mandipadk7/kavi

TypeScript · Node.js 25 · node:sqlite · Claude Code hooks · Codex app-server · git worktrees · JSON-RPC

1.5.3 on npm · MIT · Node 25+

225
tests across 46 files
0
runtime npm dependencies
2
agents, one worktree each

Architecture

The TUI talks to a daemon over a Unix socket using JSON-RPC. The daemon owns the router, scheduler, planner, Brain and approval engine. Claude Code is spawned with generated settings that install a PreToolUse hook on Bash, Edit, Write and MultiEdit; Codex runs as codex app-server over stdio with approvals on request.

Each agent gets one detached worktree per session, on branch kavi/<session>/<agent>. kavi land merges both back to the base branch after overlap detection and the configured validation command.

        ┌──────────────────────┐
        │ Kavi TUI (raw ANSI)  │
        └──────────┬───────────┘
                   │ Unix socket, JSON-RPC
        ┌──────────▼───────────┐
        │ daemon: router ·     │
        │ scheduler · brain ·  │
        │ approvals · ledger   │
        └─────┬──────────┬─────┘
   PreToolUse │          │ requestApproval
  ┌───────────▼──┐   ┌───▼──────────────┐
  │ claude child │   │ codex app-server │
  └──────┬───────┘   └───┬──────────────┘
  ┌──────▼───────┐   ┌───▼──────────────┐
  │ worktree     │   │ worktree         │
  │ claude-<sid> │   │ codex-<sid>      │
  └──────┬───────┘   └───┬──────────────┘
         └──────┬────────┘
                ▼  kavi land (overlap check)
           base branch

Routing

The router tries path-ownership globs from .kavi/kavi.toml first, then domain keywords, then an LLM classifier, and falls back to Codex. Every decision goes into a decision ledger with a confidence. Larger goals become a DAG of tasks that run in parallel where dependencies allow.

Approvals and missions

By default every shell command and file write from either agent waits in the approvals queue; --remember reuses a decision for the session. Missions add an autonomy policy — guided, autonomous, or overnight.

Shadow missions rerun a goal with a different prompt and rank the variants on acceptance, health, risk, overlap and cost. The Brain keeps facts, decisions, procedures and risks across tasks.

Design choices

No UI or database dependencies. The TUI is raw escape codes plus readline, storage is Node 25's built-in node:sqlite, and the build strips types with node:module — no tsc, no bundler. Session state is a JSON record next to an append-only JSONL event log.