Skip to main content

Agentic sessions — configuring the Architect and Implementer

Every Kiwi task runs the same way: a persistent Architect plans the task and reviews each round, and an agentic Implementer does the editing with real tools. This is the only execution loop — there is no separate mode to opt into. See The Data Plane daemon for how the loop itself works round to round; this page covers what you can configure and how to read the result.

Picking models​

The Implementer and the Architect can run on different models, and usually should — the Architect is called a handful of times per task, while the Implementer runs constantly, so a fast, cheap model for the Implementer paired with a more capable one for the Architect is the intended split.

CLI​

kiwi submit -task "Add a Modulo function mirroring Divide, with table-driven tests" \
    -repo https://github.com/you/yourrepo -ref main \
    -model claude-haiku-4-5-20251001 \
    -architect-model claude-sonnet-5

-architect-model is optional and defaults to the platform default (currently claude-opus-4-8) rather than to -model, so a submit that names only a worker model still gets a genuinely different, more capable reviewer rather than silently reviewing itself.

Dashboard & API​

In the API, SubmitTaskRequest takes model and, optionally, architect_model. In the dashboard, set both under the task composer's model picker.

-mode / mode is accepted and ignored​

The CLI, API, and SDKs still accept a mode field — kiwi submit -mode prints a notice — so nothing written against the old two-mode API breaks. It selects nothing: there is only one loop.

Fresh context per round, briefed from durable state​

The Implementer starts a new conversation every round rather than carrying forward a live transcript, which becomes a lossy, stale cache of the filesystem the longer it grows. What survives between rounds is durable, structured state: the Architect's spec, a compact digest of what earlier rounds did, and — since a round can raise questions it couldn't resolve on its own — the Architect's answers to them. Combined with prompt caching within a round, this keeps a multi-round session cost-effective without the exponential blowup that plagues long-running agent transcripts. See The Data Plane daemon for the full round structure.

Resuming from a PR review comment​

Leaving a review comment on a Kiwi PR resumes the task: a new round starts, carrying context from the parent task's outcome, rather than requiring a full re-run of the session or being silently ignored. Configure how Kiwi responds to comments with an org's PRCommentMode — off, mention (default — Kiwi acts only when it is spoken to), or any.

Sandbox isolation​

Like every Kiwi run, a session executes all model-generated code (via tools) inside an isolated sandbox — see Sandbox & isolation for the two-phase install/verify split that applies here too.

By default, the sandbox in a session receives no credentials at all beyond what the two-phase split already provides. This protects your git token and other secrets while the Implementer explores the repository and runs arbitrary commands. If your test commands require credentials of their own, opt in explicitly with KIWI_SESSION_ALLOW_TEST_CREDS=true.