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 active model is exposed as a session config option (configId: "model") — a select type listing all available models plus a Multi-Model entry. 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.

Clients can read the current model from the configOptions returned by session creation or load, and change it at any time via setSessionConfigOption with configId: "model". The value is either a model ref in provider/modelId format or "multi-model". 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.

Slash commands

ACP sessions support slash commands. When a session starts or is resumed, the client receives an available_commands_update notification listing the commands the agent supports. The client can then present these commands in its UI (e.g. a command palette) and execute them on behalf of the user.

Currently available commands:

Command	Description
`/bug`	Report a bug — opens a pre-filled GitHub issue form. Accepts an optional title as input.

Slash commands that require user interaction — such as confirmations, text input, or selection pickers — surface those prompts to the ACP client automatically. If the client does not support a particular prompt type, the agent treats it as a dismissal and continues without crashing.

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.
Authentication RPC	`authenticate()` is a stub — returns `{}`.
Slash commands	Most slash commands require the TUI and have no effect in ACP mode. Only `/bug` and `/permissions` are fully functional in ACP sessions.

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

If a tool call completes but shows no content, check the harness logs for errors. Text and image tool results are forwarded to the client automatically. MCP resource blocks are converted to text by the MCP bridge before reaching the ACP layer.