Ferment

Ferment is Kimchi's autonomous project mode. Describe a goal — "Build Tetris", "Add Google OAuth login", "Migrate the API to async/await" — and the harness breaks it into phases, executes each one using specialised subagent workers, grades the results, and picks up exactly where it left off if a session ends.

Where regular chat mode handles one-off tasks, Ferment handles projects: multi-step work that spans sessions and benefits from structured planning, execution tracking, and persistent context.

Ferment runs with --yolo permissions — the agent reads, writes, and executes shell commands without prompting for approval. Permissions are elevated as soon as you approve ferment creation (from the draft state onward), so the scoping and execution flow can proceed without interruption. You shape the work during scoping and at phase boundaries (in manual mode), not at individual tool calls.

The core idea

Every ferment is a single JSON file on disk. The harness reads the file at session start, a deterministic engine decides what to do next, and every action — activating a phase, completing a step, recording a decision — updates the file immediately. If the process crashes or the session ends, the next session resumes from exactly where it left off.

The plan is the state. There is no separate execution log, no external database, and no synchronisation protocol. The file is the complete, authoritative record of the project.

Concepts

A ferment is organised into a hierarchy:

Ferment  ← the project ("Build Tetris")
│
├── Scoping   (goal, success criteria, constraints, assumptions)
├── Decisions (architectural choices that shaped the work)
├── Memories  (conventions, gotchas, patterns discovered along the way)
│
└── Phases  ← milestones (1–7 recommended)
    │
    └── Steps  ← concrete tasks (3–6 per phase)

Ferment — the top-level project container. Each ferment has a name, scoping answers, and one or more phases.

Phases — milestones that organise work into logical slices. Phases execute sequentially by default, or in parallel when grouped (see Parallel phases below).

Steps — concrete tasks within a phase. Each step has a description, an optional verification command, and a worker model assignment. Steps are executed by subagent workers or directly by the orchestrator, depending on the model configuration, and graded on completion. In multi-model mode, steps are always delegated to subagent workers; in single-model mode, the orchestrator may execute steps directly when that is more efficient.

Lifecycle

A ferment moves through a predictable set of statuses:

Phases follow their own lifecycle: planned → active → completed / skipped / failed. Steps follow: pending → running → done / verified / skipped / failed.

When a ferment transitions from running to having no active phases, it returns to the planned state, ready for the next phase to be activated.

Starting a ferment

Run /ferment (or /ferment new "Name") from the Kimchi prompt. The agent opens an interactive picker and walks you through scoping.

Scoping

When a ferment is created, the agent follows a structured orient-interview-plan scoping flow:

1. Orient — The agent does a lightweight scan of the project — file listing, README, config files, and short entrypoint snippets — to build an initial mental model. It identifies unknowns and assumptions but does not ask questions yet. For greenfield projects with no existing codebase, this step is noted and skipped.
2. Interview — The agent asks you about the unknowns identified during orientation. Questions are asked in iterative rounds: after each round of answers, the agent reflects on how the answers change its understanding and whether new questions have emerged. Questions are only asked when genuinely needed — ambiguous intent, assumptions that could be wrong, or decisions only you can make. For broad discovery or planning requests, the agent may ask which improvement areas to include. If the intent is clear, the agent moves on without manufacturing questions.
3. Completion criteria — The agent drafts concrete, testable criteria for what "done" looks like and confirms them with you before proceeding. This is a hard gate — scoping cannot continue until you approve the criteria.
4. Codebase exploration — For existing codebases, the agent investigates implementation-specific details using targeted reads and Explore subagents, focusing on unknowns that remain after the interview. Skipped for greenfield tasks with no existing codebase.
5. Plan proposal — The agent synthesises everything into a structured scope: a concise title, goal, success criteria, constraints, assumptions, and 1–7 phases.

Once you confirm the plan, the ferment transitions to planned.

Continuation policy

Continuation policy controls how the ferment advances between phases:

Each new ferment starts with the default policy for its session type: manual for interactive sessions, automated for one-shot or headless sessions. Policy does not carry over from a previous ferment in the same session.

Switch at any time:

/ferment manual
/ferment auto

Pause, resume, and exit are separate lifecycle controls — /ferment pause halts the lifecycle, /ferment resume continues it using whichever policy is active. /ferment exit leaves Ferment mode without deleting or abandoning the ferment; planned or running work is paused first, active Ferment UI and tools are cleared, and you can later select it from /ferment list or /ferment switch.

Pressing Esc or Ctrl+C during a ferment session automatically pauses the ferment if it is running or planned. You'll see a notification confirming the pause — run /ferment resume to pick up where you left off.

Grading

After every step and phase completes, an autonomous judge evaluates the work and assigns a letter grade. A low grade may block phase advancement and prompt the agent to rework before continuing.

Grades appear in the dashboard widget and the /ferment progress overlay. They're also injected into the planner's context so later phases can learn from earlier results.

Decisions and memories

The planner captures knowledge that persists across phases and sessions:

Decisions are architectural or design choices:

D001: Use Canvas API — better performance than DOM for grid rendering
D002: Single game loop at 60fps — simpler than event-driven approach

Memories are conventions, gotchas, and patterns:

M001 [gotcha]: requestAnimationFrame drops frames if loop takes >16ms
M002 [convention]: All piece coordinates are relative to their bounding box
M003 [pattern]: Use Uint8Array for grid — faster collision detection

Both are automatically injected into every phase activation — so Phase 4 knows what Phase 1 decided without repeating context.

Parallel phases

Phases with the same parallel group number activate and run simultaneously. When scoping, the agent may propose parallel phases where the work is independent:

Phase 3: "Backend API"    (parallel group 1)
Phase 4: "Frontend UI"    (parallel group 1)
Phase 5: "Deploy"         (sequential — runs after both complete)

The planner activates both group-1 phases at once, spawns subagents for each concurrently, and only moves to Phase 5 once both are done. Parallel phases are marked with ∥ in the dashboard.

Dashboard and progress tracking

The dashboard widget is always visible above the editor while a ferment is running:

Build Tetris  [running]
  ✓  Canvas & Grid      3/3  A
  ▶  Piece Definitions  1/3
       ▶  Define I and O pieces as 4-cell arrays…
       ○  Define S, Z, T, L, J pieces…
       ○  Render a preview of each piece…
  ○  Movement & Rotation  0/3
  ○  Scoring  0/3

Run /ferment progress for the full phase/step navigator with grades and available actions. The overlay stays live while the agent works — you can leave it open and watch progress update in place. It shows currently running steps alongside completed ones, so you always know what's happening now, not just what's done.

The status line at the bottom of the screen shows ferment progress whenever a ferment is active.

Context budget

Long-running ferments accumulate session context across many phases and steps. To keep the agent focused and token-efficient, the harness automatically compacts the session after every successful step or phase completion. The compaction summarises prior context while preserving the ferment plan, active phase, completed work, and next action — so each new step or phase starts with a fresh, focused session.

The dashboard also tracks assistant turns in the current session:

At 50+ turns, model quality tends to degrade. You can still run /compact manually at any time, or finish the current phase and let the next session start fresh.

Ferment also compacts automatically at stage boundaries — when a step or phase completes and the next one begins. This keeps the context window fresh across long-running ferments without manual intervention. See the Ferment reference for details on configuring the compaction model.

Stuck-loop protection

If the agent attempts to start the same step three or more times without completing it, the harness blocks further starts and surfaces a recovery prompt:

⚠ Stuck loop detected: step 2 "Implement collision detection" has been started
  3 times without completing. Should we retry with a revised approach, skip
  this step, or pause the ferment?

The block stays active until the step is completed or skipped.

Error and crash recovery

If a connection error or crash interrupts a ferment, the harness pauses it automatically and notifies you. Run /ferment resume to continue from where you left off.

When to use Ferment

Related resources