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 needs an execution-capable permission mode to run. When you approve a ferment's plan, the harness presents an elevation gate — a prompt asking whether to elevate to the highest execution mode your organization's policy allows (yolo if allowed, otherwise auto). You do not need to pass --yolo yourself.

Elevation gate

The gate follows a ladder based on your current permission mode:

If no execution mode (auto or yolo) is allowed by the policy, the ferment runs degraded without asking. If the policy only allows plan mode, ferment cannot run at all — /ferment, /ferment new, /ferment one-shot, and headless resumes are refused with a message explaining the restriction.

Degraded mode

When you decline the elevation gate, the ferment continues in your current mode with per-ferment manual continuation. Background steps that need tool-call approval stall until you respond, and the ferment pauses at every phase boundary regardless of the session's continuation policy. Only the declined ferment is affected — other ferments in the same process keep their own continuation policy.

Switching the ferment to automated continuation (with /ferment auto) or accepting a later elevation gate clears the degraded state.

Elevation lifecycle

When the ferment completes or is abandoned, the ferment-owned elevation is reverted and permissions return to the harness default. If you manually chose a permission mode during the ferment (for example, by switching via the /permissions command or shift+tab cycling), that choice is preserved — ferment deactivation does not override an explicit user selection.

Organization policy

If your organization has set an allowed-modes policy, the harness enforces it across every entry point:

• Shift+tab cycling skips disallowed modes.
• /permissions mode and the TUI picker refuse disallowed modes.
• CLI flags (--plan, --auto, --yolo), the KIMCHI_PERMISSIONS environment variable, the permissions config defaultMode, and persisted session modes are all clamped to the nearest allowed mode on startup.
• ACP permissions-mode config option advertises only allowed modes and rejects disallowed ones.

Without a policy — no API key, fetch failure, or unreachable platform — all modes are allowed (fail-open).

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