Architecture

Kiwi Control is the repo-local control plane around your coding agents.

It does not replace Claude Code, Codex, Cursor, or Copilot. It gives them a structured repo map, current state, review guidance, validation expectations, and continuity artifacts before they start spending context.

The repository stays the source of truth. The CLI and desktop app read the same repo-local contract.

See measured proof Read internals Architecture FAQ
Developer
uses
kc CLI
derives
sj-core
writes / reads
repo-local .agent/ state
guides
Claude Code, Codex, Cursor, Copilot
Why this matters

Agent waste usually starts before implementation.

When an agent starts in a real repo without a working set, authority order, phase state, or validation map, it has to discover all of that with expensive broad reads. Kiwi Control makes those answers explicit and inspectable.

Local Repo-owned contract, no cloud-required control plane
Graph Repo map, impact, decision, history, and review surfaces
Honest Efficiency proof is measured on one controlled run, not universal
System overview

Four surfaces, one repo-local truth.

Repo authority

README, AGENTS.md, CLAUDE.md, Copilot instructions, docs, and `.agent/` files define the portable working contract.

Core engine

`packages/sj-core` derives context, graph artifacts, review packs, workflow state, checks, and token guidance.

CLI surface

`packages/sj-cli` exposes the engine through `kc status`, `guide`, `graph`, `pack`, `review`, and `check`.

Desktop surface

`apps/sj-ui` is a Tauri app that visualizes the same repo-local state and runtime bridge output.

Repo lifecycle

From unknown repo to structured agent workflow.

kc init kc status kc guide kc graph build kc pack status kc review kc check checkpoint / handoff
Before agent work

Context becomes deliberate.

Kiwi Control reads repo authority, classifies project shape, selects context within a budget, and records active role hints so an agent can start with a practical map instead of raw discovery.

During review

Risk becomes visible.

Review and graph outputs turn the current repo state into concrete files, modules, validations, and next steps. The agent still reasons, but it has fewer blind alleys.

Command map

The main surfaces line up with the repo lifecycle.

statusCurrent repo-local continuity, authority, readiness, and target state.
guideWhat to read next, what command to consider, and which specialist or pack fits.
graphRepo map, dependency, impact, history, decision, and review graph artifacts.
packScoped MCP/tool/context guidance, not fake universal tool access.
reviewRisk-ordered review context and likely missing validation guidance.
checkRepo-local contract validation and workflow expectation checks.
Token efficiency

Lower waste comes from better starting context.

Kiwi Control helps agents avoid repeated rediscovery by making repo authority, selected files, graph hints, validation expectations, and handoff state explicit. The measured proof shows this helped on one controlled task. It is not a guarantee for every repo or every model.

Narrower first read

Context selection ranks files before an agent reads broad sections of the repo.

Less repeated setup

Checkpoints, handoffs, and current-focus state preserve continuity across interruptions.

Review before drift

Review packs and checks push attention toward risk and validation before a patch grows sideways.

Open-source internals

Inspect the architecture directly.

FAQ

Common architecture questions.

Is Kiwi Control an AI agent?

No. Kiwi Control is a control plane. Claude Code, Codex, Cursor, Copilot, or a human still perform the implementation work.

Does it replace Claude Code or Codex?

No. It is designed to give those tools structured repo context and continuity before they start work.

How does it reduce wasted token usage?

It narrows the initial working set, preserves handoff state, and points review toward risky files. The public proof is one controlled measured run, not a universal benchmark.

Does it work locally?

Yes. The durable contract lives inside the repository, primarily under `.agent/`, with CLI and desktop surfaces reading that state.

What is still beta?

Installer signing trust is release-specific, Homebrew and winget are not live install paths, and some usage/advisory views depend on local tool availability.

Questions

Ask about the internals, proof, or release path.

Use GitHub for reproducible issues, LinkedIn for direct product questions, or email Shrey if you need a deeper architecture conversation.

Open a GitHub issue Reach Shrey on LinkedIn Email Shrey