How to Use Agent Client Protocol (ACP) to Integrate Kimi Code with Zed or JetBrains

Kimi Code provides an ACP adapter that enables Zed and JetBrains IDEs to communicate with the AI agent via STDIO JSON-RPC, exposing sessions, slash commands, and tool calls through the Agent Client Protocol 0.23.

The MoonshotAI/kimi-code repository ships with a first-party adapter (@moonshot-ai/acp-adapter) that implements the Agent Client Protocol specification. This allows any IDE supporting ACP—such as Zed or JetBrains AI Chat—to launch Kimi Code as a subprocess, establishing a bidirectional JSON-RPC stream over standard input and output without requiring native IDE plugins.

ACP Architecture Overview

The integration relies on three distinct layers inside the Kimi Code codebase:

• CLI Entry Point – The apps/kimi-code/src/cli/sub/acp.ts file defines the kimi acp subcommand. It suppresses banners to keep the STDIO pipe clean, writes diagnostic logs to stderr, and initializes the server.
• Protocol Adapter – packages/acp-adapter/src/server.ts implements the JSON-RPC surface, registering both stable methods (session/new, tool/call) and unstable extensions (inline-edit prediction, buffer sync).
• Domain Bridge – Files like packages/acp-adapter/src/kaos-acp.ts translate ACP workspace concepts into Kimi Code’s internal Kaos file system, while packages/acp-adapter/src/modes.ts and packages/acp-adapter/src/auth-methods.ts handle IDE-specific UI contracts.

Configuring Zed for ACP Integration

Zed recognizes Kimi Code as an agent server through its settings file. Add the following configuration block to ~/.config/zed/settings.json:

{
  "agent_servers": [
    {
      "type": "terminal",
      "command": ["kimi", "acp"],
      "env": {}
    }
  ]
}

When Zed initializes the connection, it launches the kimi acp process and waits for the initialize response. The packages/acp-adapter/src/modes.ts module automatically constructs the mode dropdown options (e.g., "Default", "Low effort") that populate Zed’s chip-strip UI, ensuring the order matches Zed’s expected contract.

Configuring JetBrains for ACP Integration

For JetBrains AI Chat, configure the external agent settings to point at the Kimi Code CLI:

1. Open AI Chat > Settings > External Agent.
2. Set the command to kimi acp.
3. Save the run configuration.

JetBrains sends the same initialize request as Zed, receiving the supported modes and authentication methods advertised by packages/acp-adapter/src/auth-methods.ts.

The JSON-RPC Communication Flow

Initialization Handshake

When the IDE launches kimi acp, the process defined in apps/kimi-code/src/cli/sub/acp.ts waits for an initialize request:

// IDE → Kimi Code
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": { "name": "Zed", "version": "0.25.0" },
    "agentServers": [{ "type": "terminal", "env": {} }]
  }
}

The server responds with capabilities and available modes:

// Kimi Code → IDE
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "capabilities": { "sessions": true },
    "modes": [
      { "id": "default", "label": "Default" },
      { "id": "thinking-low", "label": "Low effort" }
    ]
  }
}

Session Management and Mode Handling

Both IDEs create sessions via the session/new method. The packages/acp-adapter/src/session.ts file handles session lifecycle, mapping IDE requests to internal Session objects.

When users change modes via the UI, the IDE sends session/configOption. The adapter updates the underlying session configuration, allowing real-time switching between thinking modes without restarting the connection.

Authentication via Terminal-Auth

Zed (without the AcpBetaFeatureFlag) and JetBrains rely on the terminal-auth method defined in packages/acp-adapter/src/auth-methods.ts. During initialization, the server advertises this method. The IDE renders a password prompt, collects credentials, and forwards them to the adapter, which then exchanges them for OAuth tokens via Kimi Code’s internal OAuth manager.

Executing Slash Commands and Tool Calls

User input starting with / (e.g., /list-files) arrives as ContentBlock messages. The session handler in packages/acp-adapter/src/session.ts parses these as slash commands and dispatches them to Kimi Code’s internal command router.

For long-running operations, the server streams tool/callUpdate notifications:

// Kimi Code → IDE (streaming progress)
{
  "jsonrpc": "2.0",
  "method": "tool/callUpdate",
  "params": {
    "callId": "t_42",
    "output": "Generating answer…"
  }
}

This incremental update mechanism allows Zed to display progress indicators during tool execution.

Workspace and File System Bridge

The packages/acp-adapter/src/kaos-acp.ts file implements the Kaos-ACP bridge, which synchronizes the IDE’s view of the workspace with Kimi Code’s file system:

• Converts ACP’s MCP server list into Kaos FileSystem objects.
• Emits file-change events for tools that read or write paths.
• Allows the IDE to forward MCP servers (such as language servers) to the agent side.

This bridge enables Zed’s "unsaved-buffer view" and JetBrains’ project structure to remain consistent with Kimi Code’s internal state.

Practical Implementation Examples

Launching the ACP Server

From a terminal or IDE configuration:

kimi acp

The process reads JSON-RPC from stdin and writes structured logs to stderr, keeping the RPC channel clean.

Complete Message Exchange

// Create session
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/new",
  "params": { "model": "gpt-4o-mini" }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessionId": "s_01",
    "modes": [{ "id": "default", "selected": true }]
  }
}

// Submit query
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/ask",
  "params": { "sessionId": "s_01", "content": "Explain ACP integration." }
}

Zed Configuration Snippet

{
  "agent_servers": [
    {
      "type": "terminal",
      "command": ["kimi", "acp"],
      "env": { "KIMI_LOG_LEVEL": "info" }
    }
  ]
}

JetBrains Run Configuration

# AI Chat > Settings > External Agent

Command: kimi acp

Summary

• STDIO Transport – The kimi acp command (apps/kimi-code/src/cli/sub/acp.ts) provides a banner-free JSON-RPC interface over stdin/stdout.
• Protocol Implementation – packages/acp-adapter/src/server.ts exposes stable methods (sessions, tools) and unstable extensions for IDE integration.
• IDE Configuration – Zed uses ~/.config/zed/settings.json; JetBrains uses the AI Chat external agent settings to launch the subprocess.
• Authentication – Terminal-auth method (packages/acp-adapter/src/auth-methods.ts) enables OAuth flows within the IDE’s native UI.
• Workspace Sync – The Kaos-ACP bridge (packages/acp-adapter/src/kaos-acp.ts) maps IDE file systems and MCP servers into Kimi Code’s internal model.

Frequently Asked Questions

How does the ACP server handle IDE disconnections?

The packages/acp-adapter/src/server.ts implementation listens for session/close and session/end JSON-RPC messages. When Zed closes its agent panel or JetBrains stops a run configuration, the adapter cleans up the associated Session objects and releases Kaos file system resources to prevent memory leaks.

Can I use custom MCP servers with Kimi Code through ACP?

Yes. The packages/acp-adapter/src/kaos-acp.ts bridge converts the MCP server list sent during initialization into native Kaos FileSystem objects. This allows Kimi Code to access tools exposed by language servers or custom MCP implementations that the IDE forwards via the ACP channel.

What is the difference between stable and unstable ACP methods?

Stable methods—such as session/new, session/ask, and tool/call—are defined in the ACP 0.23 specification and guaranteed to remain backward compatible. Unstable methods, implemented in packages/acp-adapter/src/server.ts, include experimental features like inline-edit prediction and document buffer synchronization that may change in future releases.

How do I troubleshoot authentication failures in Zed or JetBrains?

Authentication relies on the terminal-auth method advertised in packages/acp-adapter/src/auth-methods.ts. If the IDE fails to prompt for credentials, verify that the initialize response includes the terminal auth method. Check stderr output from the kimi acp process for OAuth manager errors, and ensure the IDE’s environment variables allow interactive terminal access for the password prompt.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}