Skip to main content

Agentic Session Mode

By default, Kiwi uses a File Loop where a task is decomposed into file-assigned workers, and each worker makes single-turn, whole-file edits. This is extremely fast for bounded edits (e.g., "fix this bug in this file"), but less suited for complex, open-ended tasks that require deep exploration.

For complex tasks, Kiwi provides Session Mode — an agentic loop powered by two distinct roles:

  1. The Architect (Persistent): Owns the task from start to finish. It writes the spec, sets acceptance criteria, reviews the work of the Implementer, and ultimately writes the PR. It runs on an expensive, highly capable model (e.g., Claude 3.5 Sonnet or Opus-class).
  2. The Implementer (Agentic, Tool-calling): Does the actual work against the repository using real tools (read, grep, write, run). It iterates in reviewed rounds. It runs on a fast, cheaper model (e.g., Claude Haiku or Gemini Flash).

How to use it​

You can opt-in to Session Mode on a per-task basis.

CLI​

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

-architect-model is optional and defaults to -model. We strongly recommend setting it to something more capable, since the reviewer is called a handful of times per task while the implementer runs constantly and benefits from being fast and cheap.

Dashboard & API​

In the API, pass "mode": "session" in your SubmitTaskRequest. In the dashboard, toggle the Execution loop control to "Session" when submitting a new task.

Fresh context per round​

In Session Mode, the Architect maintains the durable state, while the Implementer gets a fresh context every round.

When an agentic coder works, the transcript becomes a lossy, stale cache of the filesystem. By starting fresh each round, Kiwi avoids context drift. The Implementer is seeded with:

  • The Architect's spec for the round.
  • A repo map (the file tree plus a cheap symbol index).
  • The diff so far (git diff on the job branch).
  • A brief handoff note from the previous round authored by the Implementer itself.

This approach combined with prompt caching makes Session Mode highly cost-effective, preventing the exponential input cost explosion that plagues long-running agent transcripts.

Sandbox Isolation in Session Mode​

Like the File Loop, Session Mode executes all model-generated code (via tools) inside an isolated sandbox.

By default, the sandbox in Session Mode receives no credentials at all. This protects your git token and other secrets while the agent explores the repository and runs arbitrary commands. If your test commands require credentials, you must explicitly opt-in by setting KIWI_SESSION_ALLOW_TEST_CREDS=true in your environment.