Reference

This page is the complete lookup reference for Ferment — Kimchi's autonomous project mode. For an introduction to what Ferment is and how it works, see Ferment. For a hands-on walkthrough, see Ferment: Quickstart.

Commands

All Ferment commands are available from the Kimchi prompt during a harness session.

Continuation policies

Each new ferment starts with the default policy for its session type: manual for interactive sessions, automated for one-shot or headless sessions. If you switched a previous ferment to automated with /ferment auto, that choice does not carry over — the next ferment you create resets to the default. Resuming, switching to, or re-proposing an existing ferment preserves whatever policy it was using.

Switch policies at any time with /ferment manual or /ferment auto. The active policy is independent of pause/resume — pausing halts the lifecycle regardless of policy, and resuming continues with whichever policy is set.

/ferment exit clears the active ferment from the current session. If the ferment was planned or running, exit pauses it before detaching; drafts stay drafts, paused ferments stay paused, and completed or abandoned ferments are only detached. Exit does not change the manual/automated continuation policy. To resume the ferment 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 continue from where you left off.

Lifecycle states

Ferment

Phase

Step

Grading

An autonomous judge evaluates every completed step and phase 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 /ferment progress overlay.

Compaction

Ferment automatically compacts context 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 /compact intervention. The compaction summarises completed work and carries the plan, decisions, memories, and grading context forward to the next stage.

Compactor model

To use a different model for stage-boundary compaction, set the compactor role in ~/.config/kimchi/harness/settings.json:

{
  "modelRoles": {
    "compactor": "model-name"
  }
}

The compactor model is not configurable via the /multi-model picker — use the settings file.

Stuck-loop protection

If the same step is started three or more times without a completion, 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 clears when the step is completed or skipped.

Permissions

Ferment operates at the --yolo permissions level — the agent and all subagent workers read files, write files, and execute shell commands without prompting for approval. Permissions are elevated as soon as you approve ferment creation (from the draft state onward), so scoping and execution proceed without interruption. You do not need to pass --yolo yourself. When the ferment completes or is abandoned, the ferment-owned elevation is reverted and permissions return to the harness default. However, if you manually chose a permission mode (for example, by switching to yolo via the /permissions command or shift+tab cycling), that choice is preserved — ferment deactivation does not override an explicit user selection.

Headless usage

Ferment works without a TUI — useful for CI, scripts, and background runs.

One-shot task

/ferment one-shot "Add OpenAPI spec export to the REST API"

Creates a ferment, scopes it automatically, and begins execution without interactive input.

One-shot ferments are safe to run in CI and scripted pipelines — transient provider errors are retried automatically, and the ferment always exits in a terminal state (either complete or abandoned) so nothing is left waiting for manual intervention.

Headless session

Run Kimchi in headless mode with a pre-existing ferment:

KIMCHI_ACTIVE_FERMENT=<ferment-id> kimchi --headless

The session resumes the ferment, executes the next action, and continues until the ferment completes, pauses, or encounters an error. State is written to disk before exit so the next invocation can continue.

State file

Each ferment is stored as a single JSON file:

.kimchi/ferments/<uuid>.json

This file is the authoritative source of truth. You can inspect it directly, back it up, or copy it between machines. The schema is stable across harness versions.

Related resources