kimchi: a terminal coding agent that routes work across several models

A CLI agent whose differentiator is routing, not the agent loop

kimchi describes itself as a coding agent CLI built on the pi-mono coding agent SDK from badlogic. That base matters, because it means the agent loop itself is not the project's contribution. The agent loop is where a model reads a repository, runs tools, and iterates until the task is done, and several projects already do that well.

The contribution is on top of it: multi-model orchestration. An orchestrator model receives each task, classifies it, and delegates to whichever model holds that role. The status line shows `multi-model (orchestrator-id)` in that mode and a plain model name in single-model mode, so which mode you are in is always visible.

Switching is deliberately quick. `ctrl+p` cycles models in the interactive CLI, and the last entry in the cycle is `multi-model`, so it is one keystroke away rather than a config edit. The `/model` picker lists specific models plus multi-model.

The project is Apache-2.0, written in TypeScript, with 2232 stars and 146 forks across 43 open issues. It is not archived and the last push was on 2026-09-28, which is very recent, and release tags are at v1.1.37 with a parallel canary channel.

Installation has three paths and a Windows wrinkle

Homebrew covers macOS and Linux:

brew install getkimchi/tap/kimchi

The install script is the fallback for the same platforms, and it runs in memory rather than writing a file to disk first:

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

Windows uses PowerShell, and the README explains why the one-liner works despite execution policy:

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

The reason is that piping runs the installer in memory, so the `Restricted` policy that blocks running a downloaded `.ps1` file does not apply. If you download the file and want to run it as a file, the documented form is `powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1`, and the README is explicit that the bypass applies only to that invocation rather than changing system policy.

After installing, setup is interactive and one-time:

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

The repository tree suggests a more mature project than the README alone conveys: a `benchmark/` directory, `test-cases/`, both `vitest` config and smoke tests, end-to-end TUI tests with a trace and replay mode, a `docker/` directory, `themes/` for the terminal UI, and an `extensions/` directory holding the memory subsystem.

Roles are the unit of configuration

In multi-model mode each task type belongs to a role. Six are defined, and the defaults are hardcoded in `DEFAULT_MODEL_ROLES`:

{
  "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"
  }
}

The configuration file is `~/.config/kimchi/harness/settings.json`, editable directly or through the `/multi-model` command in the CLI. Because defaults exist, you only need to list the values you are changing; missing keys fall back.

A role is either one model or a pool. The orchestrator reads tier and description and picks the best fit, which is the mechanism that makes a pool more than a random choice.

The six roles have distinct jobs. The orchestrator runs the main loop, classifies tasks and delegates, and is single-model by definition. The planner designs the approach and writes specs, and when it is the same model as the orchestrator, planning happens in-process rather than as a separate call. The builder implements code, the reviewer reviews it, the explorer navigates files and traces architecture, and the researcher goes outside the codebase for web search and documentation lookup.

Delegation is phrased as explicit per-phase directives

The mechanism is more concrete than the marketing term suggests. The orchestrator receives per-phase directives generated from the role configuration, one for each pipeline phase of plan, build, review, explore and research, and the phrasing of each directive depends on whether the orchestrator's own model ID appears in that role's pool.

If the orchestrator owns the role, the directive tells it to perform the work itself. If it does not own the role, the directive names the model ID and says to delegate to the agent tool. Review is the exception: it is always delegated, even when the orchestrator holds the reviewer role, so that review happens in a fresh context and the model reviewing code is not the same context that wrote it.

That single rule is a design opinion worth noting. Self-review in the same context tends to confirm whatever the model just did, and paying for a second context is cheaper than debugging code that was never actually checked.

Tier selection follows the same logic. When a pool has several models, the orchestrator takes the lightest tier that fits and escalates to heavy only for complex work such as concurrency or algorithms, or as a retry after a standard-tier model has failed. So a heavy model is a fallback and an escalation path, not the default route.

External models need metadata or routing is arbitrary

The sharpest practical detail in the README concerns external models. Built-in `kimchi-dev` models have tier and description baked in. Anything from Anthropic, OpenAI or another provider has neither, so it defaults to `standard` tier, `vision: false`, and an auto-generated description derived from its assigned roles.

The consequence is that a strong external model and a weak one look identical to the orchestrator unless you tell it otherwise. The README puts it plainly: without metadata, both models look like standard-tier and selection is arbitrary.

The fix is a `modelMetadata` section:

{
  "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."
    }
  }
}

Three fields matter: `tier` is `light`, `standard` or `heavy` and drives complexity routing, `description` is shown to the orchestrator so it can match strengths to requirements, and `vision` records whether the model handles image input. With that in place the orchestrator routes simple build chunks to the lighter model and complex ones to the heavier one.

Metadata can also be edited in the app through `/multi-model` then Edit model metadata, which the README calls the only in-app path for it, and custom overrides can be reset to defaults from the same menu.

Single-model mode is not a degraded mode

It is worth being precise about what disabling orchestration keeps, because the usual assumption is that single-model means fewer features. The README says the orchestration system prompt stays active in single-model mode, along with the environment description, tool definitions, research rules, guidelines and phase tagging. What is disabled is task classification and delegation.

So single-model mode is the same agent with the same instructions, just answering every task itself. The subagent tool also remains available if you explicitly ask the agent to delegate, which means you can use a lighter model for routine work and still pull in a subagent when it decides one is warranted.

The other half of the system is phase tracking. Every LLM request is tagged with a `phase:{name}` label for usage analytics and cost attribution, with the orchestrator setting the phase as work progresses and the status line showing it. The five phases are explore for navigating the codebase, plan for designing and writing specs, build for writing or refactoring code, review for verifying correctness, and research for investigating documentation and external sources.

This is what makes the whole design auditable. If the orchestrator is escalating to heavy models too eagerly, phase-level usage data shows it. Without attribution per phase, a multi-model setup is just an expensive black box, and cost attribution is the feature that makes the routing tunable rather than merely clever.

Editorial conclusion

The idea worth taking from this project is that model selection does not have to be a per-session decision. kimchi separates a task into phases, names the phase, and hands each one to whatever model fits, which is a more interesting approach than switching models yourself when something feels off. The configuration is a single JSON file, the defaults are hardcoded and only differences need specifying, and giving external models an explicit tier is what turns arbitrary selection into informed routing. The trade is complexity and cost: delegation adds calls, and heavier tiers only earn their place if you mark them honestly. Start in single-model mode until the phase reporting feels useful, add a `modelMetadata` tier for one external model, and only then turn on multi-model.

Frequently asked questions

Official sources

1. getkimchi/kimchi on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases