Kavi

Kavi is a local terminal control plane for managed Codex and Claude collaboration.

Current capabilities:

• kavi version and kavi --version: print the installed package version.
• kavi init: create repo-local .kavi config, prompt files, ignore rules, and bootstrap git if the folder is not already a repository.
• kavi init --home: also scaffold the user-local config file used for binary overrides.
• kavi init --no-commit: skip the bootstrap commit and let kavi open or kavi start create the first base commit later.
• kavi doctor: verify Node, Codex, Claude, git worktree support, and local readiness.
• kavi readiness: score the current repo for local-first autonomous mission readiness, with concrete remediation actions across environment, guidance, verification, evidence, memory, and autonomy.
• kavi update: check for and install a newer published Kavi package from npm.
• kavi start: start a managed session without attaching the TUI. Add --approve-all to run future Codex and Claude turns with full access and without Kavi approval prompts.
• kavi open: create a managed session with separate Codex and Claude worktrees and open the full-screen operator console, even from an empty folder or a repo with no HEAD yet. Add --approve-all to start in full-access mode.
• kavi resume: reopen the operator console for the current repo session.
• kavi summary: show a cohesive session-level view of progress, current changes, recent activity, and landing readiness.
• kavi mission: inspect the latest or a specific mission, including status, acceptance, and recent checkpoints.
• kavi mission spec, kavi mission diff, and kavi mission simulate: inspect the compiled mission packet, compare spec revisions or draft prompt changes, and review the mission simulator before execution or replanning.
• kavi mission confidence, kavi mission attention, kavi mission digest, and kavi mission morning-brief: inspect whether autopilot is safe, what happened overnight, and what needs operator attention next.
• kavi mission shadow, kavi mission compare, kavi mission arena, and kavi mission select: explore alternative mission strategies, rank shadow branches by score/risk/cost/overlap, and promote the best strategy into the active path.
• kavi mission policy: inspect or update the active mission's autonomy and recovery controls, including autopilot, auto-verify, auto-land, retry budget, and repair-failure pause behavior.
• kavi mission recover: apply guided recovery actions such as retrying failed work, resuming autopilot, and re-verifying the mission after operator intervention.
• kavi missions: inspect the mission list for the current repo session.
• kavi blueprint, kavi blueprint diff, and kavi blueprint apply: compile a greenfield product blueprint, compare it against the current mission, and promote it into the live mission packet.
• kavi accept: inspect the acceptance pack for the latest or a specific mission.
• kavi verify: run the mission acceptance checks that Kavi can execute automatically and persist the result.
• kavi brain: inspect repo-local project memory captured from prior mission plans, completed tasks, and landed work.
• kavi brain pack, kavi brain review, and kavi brain distill: inspect phase-aware memory packs, queue stale or contradictory entries for review, and distill noisy Brain entries into stronger canonical knowledge.
• kavi result: show the current or latest landed outcome as one cohesive result surface, including per-agent output and merged landing details.
• kavi plan: inspect the current execution graph that Kavi materialized from a planning pass.
• kavi contracts: inspect typed Codex/Claude contract handoffs, and kavi contract-apply, kavi contract-resolve, kavi contract-dismiss manage them explicitly from the operator surface.
• kavi receipts, kavi playback, kavi judge, kavi audit, kavi objections, and kavi postmortem: inspect proof-of-work receipts, phase-filtered mission playback, and Quality Court output, including role-specific verifier/contract/integration/risk objections.
• kavi patterns, kavi patterns studio, kavi patterns benchmark, kavi patterns compose, kavi patterns templates, and kavi portfolio: inspect personal pattern history, benchmark reusable templates, compose portfolio-backed starters, and explore repo-cluster relationships, command habits, and starting-point recommendations across your local portfolio.
• kavi status: inspect session health, task counts, and configured routing ownership rules from any terminal.
• kavi activity: show the session as a linear activity stream instead of raw daemon events.
• kavi route: preview how Kavi would route a prompt before enqueuing it.
• kavi routes: inspect recent task routing decisions with strategy, confidence, and metadata.
• kavi paths: inspect resolved repo-local, user-local, worktree, and runtime paths.
• kavi task: enqueue a task for codex, claude, or auto routing, with --plan and --direct to override Kavi's automatic planner decision.
• kavi retry: requeue a failed or blocked task after operator intervention, resetting its automatic retry budget for the next run.
• kavi recommend: inspect integration, handoff, and ownership-configuration recommendations derived from live claims, reviews, and routing state, with filters for kind, target agent, and active vs dismissed status.
• kavi recommend-apply: turn an actionable handoff or integration recommendation into a queued managed task.
• kavi recommend-dismiss and kavi recommend-restore: manage the recommendation inbox without losing the underlying session context.
• kavi tasks: inspect the session task list with summaries and artifact availability.
• kavi task-output: inspect the normalized envelope and raw output for a completed task.
• kavi decisions: inspect the persisted routing, approval, task, and integration decisions.
• kavi claims: inspect active or historical path claims.
• kavi reviews: inspect persisted operator review threads and linked follow-up tasks, with filters for agent, assignee, disposition, and status.
• kavi approvals: inspect the approval inbox.
• kavi approve and kavi deny: resolve a pending approval request, optionally with --remember.
• kavi events: inspect recent daemon and task events.
• kavi stop: stop the background daemon for the current repo session.
• kavi land: snapshot dirty agent worktrees into commits, merge them in a transient integration worktree, run validation there, and then fast-forward the target branch.

Runtime model:

• Repo-local state lives under .kavi/.
• Machine-local state defaults to ~/.config/kavi and ~/.local/state/kavi.
• In restricted environments you can override those with KAVI_HOME_CONFIG_DIR and KAVI_HOME_STATE_DIR.
• User-local runtime overrides live in ~/.config/kavi/config.toml and can point Kavi at custom node, codex, and claude binaries.
• The operator surface talks to the daemon over a local control socket under the machine-local state root.
• SQLite event mirroring is opt-in with KAVI_ENABLE_SQLITE_HISTORY=1; the default event log is JSONL under .kavi/state/events.jsonl.
• Landed result reports are persisted under .kavi/state/reports/, so the latest merged outcome remains inspectable after the landing command exits.
• Missions are first-class session objects. Broad prompts create a mission, Codex can materialize an execution graph for that mission, and acceptance plus project memory persist with the mission instead of being scattered across ad hoc tasks.
• Mission packets are revisioned. Kavi records spec revisions, can diff revision-to-revision intent changes, and can compare the current mission packet against a draft prompt before you mutate the live mission.
• Project memory is repo-local and local-only. Kavi automatically captures useful summaries from plans, completed tasks, and landing reports so later mission prompts can inherit architecture facts and proven commands without re-explaining them every time.
• The mission simulator now exposes attention budget, seriality, contract coverage, gate pressure, and escalation pressure before or during execution, so broad prompts can be challenged before they become messy graphs.
• Receipts are now first-class proof-of-work artifacts. Each major mission node can record changed files, commands, verification evidence, assumptions, risks, and follow-up debt, and kavi receipts --timeline shows them as a mission narrative instead of a flat dump.
• Pattern Studio combines ranked templates, composition, conflicts, benchmark evidence, related repo clusters, cluster insights, starting points, and anti-pattern signals so portfolio memory is inspectable before it influences a mission.
• The operator console now opens on an activity-first view so the session reads like a linear progress log, while still exposing dedicated results, task board, dual agent lanes, approvals, diff review, and persisted operator review threads when you need to drill in.
• Routing can now use explicit path ownership rules from .kavi/config.toml via [routing].codex_paths and [routing].claude_paths, so known parts of the tree can bypass looser keyword or AI routing.
• Validation is optional by default for new repos. Set validation_command in .kavi/config.toml once the project has a real test or build command you want Kavi to enforce during land.
• Ownership routing now prefers the strongest matching rule, not just the side with the most raw glob hits, and route metadata records the winning rule when one exists.
• Diff-based path claims now release older overlapping same-agent claims automatically, so the active claim set stays closer to each managed worktree's current unlanded surface.

Notes:

• kavi init and kavi open now support the "empty folder to first managed session" path. If no git repo exists, Kavi initializes one; if git exists but no HEAD exists yet, Kavi creates the bootstrap commit it needs for worktrees.
• Codex runs through codex app-server in managed mode, so Codex-side approvals now land in the same Kavi inbox as Claude hook approvals.
• Claude still runs through the installed claude CLI with Kavi-managed hooks and approval decisions.
• --approve-all and the operator console's ! toggle switch Kavi into a full-access mode for future turns. In that mode, Claude runs with --dangerously-skip-permissions, Codex runs with its no-approval danger-full-access equivalent, and Kavi stops prompting for approvals on those future turns.
• kavi doctor now checks Claude auth readiness with claude auth status, and startup blocks if Claude is installed but not authenticated.
• kavi readiness is intentionally different from a hosted “agent readiness dashboard”: it uses local Kavi evidence, receipts, drift, Brain, patterns, and mission policy to score whether this repo is actually ready for sustained autonomous work on this machine.
• kavi doctor also validates ownership path rules for duplicates, repo escapes, and absolute-path mistakes before those rules affect routing.
• kavi doctor now also flags overlapping cross-agent ownership rules that do not produce a clear specificity winner.
• The dashboard and operator commands now use the daemon's local RPC socket instead of editing session files directly, and the TUI stays updated from pushed daemon snapshots rather than polling.
• The socket is machine-local rather than repo-local to avoid Unix socket path-length issues in deep repos and temp directories.
• The console is keyboard-driven: 1-9 switch views, j/k move selection, [ and ] cycle task detail sections, , and . cycle changed files, { and } cycle patch hunks, A/C/Q/M add review notes, o/O cycle existing threads, T reply, E edit, R resolve or reopen, a cycle thread assignee, w mark a thread as won't-fix, x mark it as accepted-risk, F queue a fix task, H queue a handoff task, t retries the selected failed or blocked task, y/n resolve approvals, ! toggles full-access mode, L lands managed work directly from the TUI, and c opens the inline task composer with live route and planning diagnostics. Inside the composer, digits are treated as literal text, Tab cycles the route owner, Ctrl+P cycles planning mode, and long multiline pastes open the expanded editor where Ctrl+S submits.
• Broad prompts no longer get split locally inside the composer. When planning mode is used, Codex materializes an execution graph after submit, the Results surface shows that graph, and the daemon schedules the resulting tasks with dependency-aware, cross-agent execution.
• The default operator mental model is now mission-first rather than task-first. The Mission tab shows the current mission summary, acceptance status, execution graph, and recent checkpoints before you need to drill into raw per-task detail.
• Mission recovery controls are first-class. Use kavi mission policy latest --guided|--autonomous|--overnight|--inspect --autopilot on|off --auto-verify on|off --auto-land on|off --pause-on-repair-failure on|off --retry-budget N to tune the current mission without editing files.
• Tabs now surface attention markers when new results, approvals, or follow-up-worthy changes appear, so the next place to look is visible from the header instead of being implied.
• Review filters are available both in the CLI and the TUI: kavi reviews --assignee operator --status open, and inside the console use u, v, and d to cycle assignee, status, and disposition filters for the active diff context.
• The Mission and Results views now expose recovery controls directly in the console. Use u to cycle autonomy, a to toggle autopilot, V to toggle auto-verify, J to toggle auto-land, and K to toggle pause-on-repair-failure for the active mission.
• The Brain view now supports deeper curation: e cycles graph mode, P cycles path-focus lenses, and o/O traverse evidence targets as well as related entries when Brain focus is active.
• The playback surface is phase-aware. Use kavi playback --phase spec|execution|repair|contracts|acceptance|landing|audit to inspect one slice of a mission timeline instead of the full mixed history.
• The claims inspector now shows active overlap hotspots and ownership-rule conflicts so routing pressure points are visible directly in the operator surface.
• The claims and decision inspectors now also show recommendation-driven next actions, so hotspots, cross-agent review pressure, and ownership-config problems can be turned into follow-up tasks directly from the operator surface.
• Recommendations now have a persisted lifecycle of their own: they can be dismissed, restored, and tracked across follow-up tasks, and repeated applies are guarded when an open follow-up task already exists.
• Review threads now carry explicit assignees and richer dispositions, including accepted risk and won't fix, instead of relying only on free-form note text.
• Successful follow-up tasks now auto-resolve linked open review threads, landed follow-up work marks those resolved threads as landed, and replying to a resolved thread reopens it.
• kavi update --check reports newer published builds without installing them, and kavi update can apply a chosen latest, beta, or exact version after confirmation.
• The operator console now includes a dedicated recommendations view. Use 4 to switch there, Enter to apply a recommendation, P to force an additional follow-up task when one is already open, z to dismiss, and Z to restore.
• kavi land now prints a clearer merged-result summary, including the pre-land change surface by agent, validation status, and how many review threads were landed as part of the merge.
• kavi land will now refuse to land when the latest mission still has a failed acceptance pack or unresolved actionable follow-up recommendations. Use kavi verify latest and the Recommendations/Mission surfaces before landing.
• After kavi land, run kavi result to inspect the persisted merged-result report and the latest per-agent outcome in one place.

Install commands:

# stable
npm install -g @mandipadk7/kavi

# beta channel
npm install -g @mandipadk7/kavi@beta

# one-off
npx @mandipadk7/kavi help

User-local config example:

version = 1

[runtime]
node_bin = ""
codex_bin = "codex"
claude_bin = "claude"

Planned release shape:

• npm global install: npm install -g @mandipadk7/kavi
• one-off use: npx @mandipadk7/kavi
• optional native installer script or package-managed distribution after the npm workflow is stable