ACP

This tutorial configures Kimchi as an ACP (Agent Client Protocol) agent in your IDE — letting JetBrains and VS Code spawn Kimchi natively, with full tool call support, file edits, and smart model routing built in.

No provider URL configuration. No custom extension logic. Just Kimchi running as a first-class agent in your editor.

Overview

By the end of this tutorial, you'll have Kimchi available as a native agent in your JetBrains IDE or VS Code, selectable from the agent picker and ready to use without any additional configuration.

This tutorial is intended for developers familiar with command-line tools and JSON configuration files.

Prerequisites

Before starting, ensure you have:

A Kimchi API key — Go to Kimchi → API Keys and click Create API key. Copy the key and store it securely.
Kimchi Coding v0.0.7 or later — Run the update command:

kimchi update

Confirm your version:

kimchi --version

📘
Kimchi's ACP mode is compatible with any IDE or editor that supports the Agent Client Protocol — including JetBrains IDEs, VS Code, and Zed. The core agent properties (command, args, env) are consistent across all tools — the surrounding configuration structure varies by tool.

Setup

MCP tools

Per-session MCP server registration is not supported. Configure your MCP tools in Kimchi's config file before starting your IDE — they'll be available in all ACP sessions automatically.

Model selection

The ACP model selector includes all available models plus a Multi-Model option. Selecting Multi-Model enables multi-model orchestration mode — the harness assigns an orchestrator model and routes subtasks to specialised models automatically. Selecting any other model switches back to single-model mode.

When multi-model mode is active, the current model ID reflects the orchestrator (e.g. multi-model/<orchestrator-ref>). For details on how multi-model orchestration works and how to configure model roles, see Multi-model orchestration.

Tool permissions

When Kimchi needs to run a tool that requires approval — such as executing a shell command or writing a file — the ACP session sends a permission request to your IDE. The IDE presents the approval prompt directly in its UI, so you can allow or deny the action without leaving your editor.

Permission choices include:

Allow once — approve this specific call only.
Allow for session — remember the approval for matching calls for the rest of the session.
Allow wildcard — remember a broader approval (e.g. all commands in a directory) for the session.
Deny — block the call and optionally tell the agent what to do differently.

Subagent workers (used internally by multi-model orchestration) do not prompt — they use the classifier to decide whether a tool call is safe, and block if confirmation would be needed.

Permission modes

You can switch between permission modes during a session to control how much autonomy the agent has:

Mode	Behaviour
default	Prompts before write operations — the agent asks before editing files or running commands.
plan	Read-only — the agent can explore the codebase but cannot make changes.
auto	The agent runs safe operations automatically and only prompts for potentially destructive ones.
yolo	No prompting — all tool calls execute immediately.

The active mode is visible in your IDE and can be changed at any time through the session settings.

Kimchi can also change the mode or model itself during a session — for example, switching from plan to default after completing a planning phase, or falling back to a different model when one is unavailable. When this happens, Kimchi sends a config_option_update notification to the IDE so the displayed mode and model stay in sync.

Current limitations

This is an early release. The following features are not yet supported:

Feature	Notes
Audio input	Non-text prompt blocks (other than images) are silently dropped. You'll see a one-time warning in stderr.
Session persistence	Each session starts fresh.
Per-session MCP servers	Configure MCP tools via Kimchi's config file instead.
Non-text tool results	Tool outputs that are only images or resource blocks come through as completed with empty content.
Authentication RPC	`authenticate()` is a stub — returns `{}`.

Troubleshooting

Kimchi doesn't appear in the agent picker

Check that the command value is an absolute path — ~/... won't work
Restart your IDE after editing the config
Run kimchi --version in your terminal to confirm the binary is accessible

Connection errors

Verify your KIMCHI_API_KEY is correct
Confirm you're on harness v0.0.7+ (kimchi update)

Tool results coming back empty

This is expected for tool outputs that return only images or MCP resource blocks — these come through as completed with empty content.