Quickstart

This quickstart walks you through creating a ferment, reviewing the plan, executing it, and monitoring progress. By the end, you'll have a running autonomous project that the harness manages across sessions.

Before you start

Kimchi Coding is installed and running — see Getting started if you haven't set it up yet.
You have a Kimchi API key configured.

📘
Ferment runs with --yolo permissions so that subagent workers can execute autonomously. Your control points are the scoping plan (Step 2) and phase boundaries in manual mode (Step 3).

Create and run your first ferment

Create a ferment

Run /ferment from the Kimchi prompt:

/ferment

The agent asks what you want to ferment. Describe your goal in plain English — for example, "Add Google OAuth login" or "Build a CLI dashboard for server stats".

If you already know the name, skip the prompt:

/ferment new "Add Google OAuth login"

The agent follows a structured orient-interview-plan scoping flow. It starts with a lightweight scan of the project to build context, then asks clarifying questions if your intent is ambiguous. Next, it drafts completion criteria and asks you to confirm them. Only after you approve the criteria does it explore the codebase in depth (for existing projects) and propose a full plan with a title, goal, success criteria, constraints, assumptions, and 1–7 phases.

Review and confirm the plan

The agent presents a markdown plan for review. You'll see the goal, constraints, and proposed phases with descriptions.

You'll see three options:

Start execution — save the plan and begin work using the current continuation policy.
Start in auto mode (run all stages without stopping) — save the plan, switch to automated continuation policy, and begin work. The agent advances through all stages without stopping at phase boundaries.
Let me say something — provide feedback to revise the plan before starting.

The ferment transitions from draft to planned and then to running as the first phase activates.

You can also revise individual scoping fields with /ferment revise goal, /ferment revise constraints, and so on.

Choose a continuation policy

By default, the ferment runs in manual mode — the agent asks before advancing to the next phase.

To let it run autonomously through all phases:

/ferment auto

To switch back to manual at any time:

/ferment manual

In manual mode, you'll see a prompt at every phase boundary with options to proceed, pause, or intervene.

Monitor progress

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

Add Google OAuth login  [running]
  ✓  Auth provider setup   3/3  A
  ▶  Session management    1/4
       ▶  Implement token storage…
       ○  Add session middleware…
       ○  Handle token refresh…
       ○  Write session tests…
  ○  UI integration  0/3
  ○  Documentation   0/2

For a full interactive view with grades and actions, run:

/ferment progress

Pause, resume, and exit

To pause the ferment lifecycle:

/ferment pause

The agent stops advancing. You can inspect the work, make manual changes, or step away.

Pressing Esc or Ctrl+C also pauses the ferment automatically if it is running or planned. You'll see a notification confirming the pause.

To resume:

/ferment resume

The agent picks up exactly where it left off, using whichever continuation policy is active. Sessions resume automatically too — if you close and reopen Kimchi with an active ferment, it continues from the last saved state. If a connection error or crash interrupted a previous session, the harness detects stale ferments on startup, pauses them, and notifies you so you can resume with /ferment resume.

To leave Ferment mode entirely without deleting the ferment:

/ferment exit

This clears the active ferment from the session. If the ferment was planned or running, it is paused first. You can select it again later from /ferment list or /ferment switch.

One-shot mode

For smaller, well-defined tasks that don't need interactive confirmation:

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

This creates a ferment, scopes it automatically, and begins execution without any prompts. Useful for CI pipelines, scripted workflows, or tasks where you trust the agent to handle the full scope.

What's next

Ferment concepts

Understand the mental model: phases, grading, decisions, memories, and parallel execution.

Ferment reference

Full command reference, environment variables, lifecycle states, and headless usage.