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 harness 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.

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.

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.