Ferment: 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.
| Command | Description |
|---|---|
/ferment | Open the interactive picker — create a new ferment or switch to an existing one |
/ferment new "Name" | Create a new ferment with the given name |
/ferment list | List all ferments |
/ferment switch <id> | Switch the active ferment by ID prefix or name |
/ferment delete <id> | Delete a ferment permanently |
/ferment abandon | Abandon the active ferment — terminal, cannot be resumed |
/ferment revise <field> | Revise a scoping field (e.g. goal, constraints) |
/ferment one-shot "task" | Create and auto-execute a single-task ferment with no interactive prompts |
/ferment progress | Toggle the phase/step navigator overlay with grades and actions |
/ferment manual | Set manual continuation policy — ask before advancing to the next phase |
/ferment auto | Set automated continuation policy — advance through phases autonomously |
/ferment pause | Pause the active ferment lifecycle |
/ferment resume | Resume the active ferment lifecycle |
/ferment exit | Leave Ferment mode without deleting the ferment |
Continuation policies
| Policy | Behaviour |
|---|---|
| Manual | Work inside the current phase continues autonomously. The agent asks before moving to the next phase. |
| Automated | The agent keeps going until the ferment is complete, blocked, paused, or needs user input. |
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.
Lifecycle states
Ferment
| Status | Description | Transitions to |
|---|---|---|
draft | Created, scoping in progress | planned, abandoned |
planned | Scoping confirmed, phases ready to execute | running, paused, complete, abandoned |
running | At least one phase is active | planned (no active phases remain), paused, complete, abandoned |
paused | Lifecycle halted — ferment tools are blocked until resume | running (active phase exists), planned (no active phase), abandoned |
complete | Explicitly finalised after all phases are terminal | — |
abandoned | Permanently stopped | — |
Phase
| Status | Description | Transitions to |
|---|---|---|
planned | Not yet started | active, skipped |
active | Currently executing | completed, skipped, failed |
completed | All steps terminal, phase graded | — |
skipped | Bypassed — counts as terminal | — |
failed | Objective not met — can be retried (active) or bypassed (skipped) | active, skipped |
Step
| Status | Description | Transitions to |
|---|---|---|
pending | Not yet started | running, skipped, failed |
running | Assigned to a subagent worker | done, verified, skipped, failed |
done | Completed, no verification command set | — |
verified | Completed and verification command passed (exit 0) | — |
skipped | Bypassed — counts as terminal | — |
failed | Objective not met — can be retried (running) or bypassed (skipped) | running, skipped |
Grading
An autonomous judge evaluates every completed step and phase and assigns a letter grade:
| Grade | Meaning |
|---|---|
| A | Excellent — objective clearly met |
| B | Good — minor gaps |
| C | Acceptable — significant gaps |
| D | Poor — objective barely met |
| F | Failed — objective not met |
Grades appear in the dashboard widget and /ferment progress overlay.
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, permissions return to the harness default.
The agent can also offer to start a ferment on your behalf when it detects substantive work. In that case, it asks a yes/no question first; permissions are not elevated until you accept. In --yolo mode, the agent skips the question and starts the ferment directly.
Environment variables
| Variable | Description |
|---|---|
KIMCHI_ACTIVE_FERMENT | Set to a ferment ID to resume that ferment on session start. Used for headless execution. |
KIMCHI_SUBAGENT | Set to 1 on worker child processes. Skips session-start rehydration to prevent re-entrancy. Not user-facing. |
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.
Headless session
Run Kimchi in headless mode with a pre-existing ferment:
KIMCHI_ACTIVE_FERMENT=<ferment-id> kimchi --headlessThe 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>.jsonThis 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.
The state file contains everything: scoping answers, phase/step definitions and statuses, grades, decisions, memories, and timestamps. No external database or service is involved.
Related resources
Updated 11 days ago