kimchi

kimchi

A coding agent CLI powered by kimchi. Built on the pi-mono coding agent SDK, kimchi gives you an AI-powered development assistant in your terminal that connects to kimchi's LLM infrastructure.

Quick start

Install the latest release:

Homebrew (macOS / Linux):

brew install getkimchi/tap/kimchi

Install script (macOS / Linux):

curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash

PowerShell (Windows):

irm https://github.com/getkimchi/kimchi/releases/latest/download/install.ps1 | iex

The one-liner runs the installer in memory, so the PowerShell execution policy does not apply to it. If you instead downloaded install.ps1 and want to run it as a file (blocked by the default Restricted policy), use:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

The bypass applies only to this invocation and does not change your system-wide execution policy. Then configure your API key and launch:

kimchi setup   # one-time interactive setup
kimchi         # launch the coding agent

Run kimchi --help to see all available subcommands and flags.

Models

Model selection

The supported model list is fetched at startup from the kimchi metadata service. Use /model or ctrl+p in the interactive CLI to switch between available models.

Kimchi operates in one of two modes:

Use ctrl+p to cycle through models. The last entry in the cycle is multi-model. You can also open the /model picker and select a specific model or multi-model from the list.

In single-model mode the orchestration system prompt (environment, tools, research rules, guidelines, phase tagging) stays active, but task classification and delegation are disabled. The subagent tool remains available if you explicitly ask the agent to delegate.

Model roles

In multi-model mode, each task type is handled by a specific role. Each role can have one model or a pool of candidates — the orchestrator reads model tier and description and picks the best fit for each task.

Use /multi-model in the interactive CLI to toggle models on/off per role, or edit ~/.config/kimchi/harness/settings.json directly:

{
  "modelRoles": {
    "orchestrator": "kimchi-dev/kimi-k2.6",
    "builder": ["kimchi-dev/minimax-m2.7", "anthropic/claude-sonnet-4-5"],
    "reviewer": "anthropic/claude-sonnet-4-5",
    "explorer": "kimchi-dev/nemotron-3-ultra-fp4"
  }
}

Defaults are hardcoded in DEFAULT_MODEL_ROLES. Roles accept any provider/model-id string or an array of strings. Only non-default values need to be specified; missing keys fall back to defaults.

How delegation works

The orchestrator receives explicit per-phase directives generated from the role configuration. For each pipeline phase (plan, build, review, explore, research), the system prompt tells the orchestrator exactly what to do:

• Roles it owns (its model ID appears in the role pool): "DO perform this work yourself."
• Roles it does not own: "DO NOT perform this work yourself. Delegate to Agent(type: X, model: Y)." — with the concrete model IDs from the pool.
• Review is always delegated, even when the orchestrator has the reviewer role, to ensure independence via a fresh context.

When a role pool has multiple models, the orchestrator picks the lightest-tier model that fits the task and escalates to heavy-tier only for complex work (concurrency, algorithms) or as a retry after a standard-tier model has failed.

Built-in models (kimchi-dev) have tier and description baked in. External models need metadata — see below.

Model metadata

External models (Anthropic, OpenAI, or any non-builtin provider) have no built-in tier or description. Without metadata, they default to standard tier, vision: false, and an auto-generated description based on their assigned roles. To give the orchestrator better routing information, add a modelMetadata section to settings.json:

{
  "modelRoles": {
    "builder": ["kimchi-dev/minimax-m2.7", "anthropic/claude-sonnet-4-5"],
    "reviewer": "anthropic/claude-sonnet-4-5"
  },
  "modelMetadata": {
    "anthropic/claude-sonnet-4-5": {
      "tier": "heavy",
      "description": "Strong general-purpose model — use for complex builds and thorough reviews."
    }
  }
}

With the metadata above, the orchestrator will use minimax for simple build chunks and Claude for complex ones. Without it, both models look like standard-tier to the orchestrator and selection is arbitrary.

Metadata can also be managed interactively via /multi-model → "Edit model metadata" — this is the only in-app path for configuring or overriding metadata, so model selection stays uninterrupted. Custom overrides can be reset to defaults from the same menu. Metadata for builtin models can be overridden the same way.

Phase tracking

Kimchi tags every LLM request with a phase:{name} label for usage analytics and cost attribution. The orchestrator sets the phase as work progresses and it is displayed in the status line.

Subagents inherit the current phase from the orchestrator but cannot change it.

Tags

Kimchi supports tagging LLM requests for usage tracking and cost attribution. Tags are included with every request and displayed in the status line, grouped by key with color coding.

Commands

Tag format

Tags use key:value format. Key and value must start and end with alphanumeric characters (middle characters may include -, _, .), each 64 characters max, 10 tags total.

Tag defaults hierarchy

Default tags are resolved from three sources, strongest first:

1. KIMCHI_TAGS environment variable (comma-separated)
2. Project config — the nearest .kimchi/tags.json found walking up from the working directory (so monorepo subdirectories pick up the repo-level file)
3. Global config — ~/.config/kimchi/tags.json

export KIMCHI_TAGS="team:backend,project:api"

Sources are unioned; when two sources define the same tag key, the stronger source's value wins. Default tags are shown with an [env], [project], or [global] marker in the /tags list; user-added tags show as [user].

Auto-tags

Two tags are added automatically to every request and do not count toward the 10 tag limit:

• model:{model_id} -- the model handling the request
• phase:{phase} -- the current work phase

Persistence

User-defined tags (added via /tags add) are persisted with the session: once a session has its own tag set (created by any /tags add, /tags remove, or /tags clear), it fully overrides the defaults above and is restored when the session resumes. KIMCHI_TAGS must be set per session; it is the strongest source while present.

Ferment V2

Ferment V2 is an experimental, branch-scoped objective controller. It keeps one objective active across turns, uses the normal Todo tools for tactical work, and does not create Ferment phases, workers, or worktrees. See the Ferment V2 runtime guide for the lifecycle and persistence contract.

Enable Ferment V2 under /resources → Experimental, then restart Kimchi. It is disabled by default.

Ferment V2 state is stored in the native session journal, so restart, resume, rewind, and fork follow the selected branch. An old turn cannot update an edited or replaced run because model updates must match both its ID and revision.

At turn_end, Ferment V2 checkpoints the current session's assistant usage and active time. Reaching a token budget stops continuation before evaluation and changes the run to budget_limited. At the later settled checkpoint, an independent tool-free evaluator returns met, impossible, or continue only while the pending-input, tool-availability, identity, and stop-condition gates permit. The fermenting time counter counts active agent turns; cancellation, repeated errors, unchanged continuation, or evaluator unavailability pause the run. Runtime accounting is for the current session; the Terminal-Bench adapter separately aggregates valid usage from all discovered session files, including nested or child files.

Ferment V2 directs the agent to track tactical progress in the normal Todos widget without creating a second feature-specific checklist. update_ferment_v2 complete records an optional runtime completion claim and ends the working turn; it never completes the run by itself. The claim response stays hidden while evaluation runs. In interactive mode, a met verdict still requires a visible, fully completed Todo list for the current revision; headless mode has no visible widget and may proceed directly from evidenced met. Both start one buffered final-answer turn. update_ferment_v2 blocked remains immediate. Regular work tools remain available while the list is created or reconciled.

Evaluation details stay out of the visible transcript. /ferment-v2 shows the evaluation count and latest verdict/reason; the evaluator uses the session model, or the configured judge role when multi-model is enabled, and records each check i