# ACP Integration with Zed and JetBrains: How Kimi CLI Connects to Your IDE

> Discover how Kimi CLI integrates ACP with Zed and JetBrains IDEs. Enable persistent agent sessions tool execution and context-aware conversations directly in your editor.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-24

---

**Kimi CLI implements an ACP (Agent Client Protocol) server that translates JSON-RPC messages between Zed or JetBrains IDEs and Kimi's internal Wire protocol, enabling persistent agent sessions, tool execution, and context-aware conversations directly within your editor.**

The MoonshotAI/kimi-cli repository ships with a built-in ACP server that transforms any ACP-compatible IDE into a frontend for the Kimi agent. By translating between the standard ACP JSON-RPC protocol and Kimi's internal Wire format, the CLI enables deep ACP integration with modern editors without requiring custom plugins for each platform.

## Core ACP Server Architecture

### ACPServer: The JSON-RPC Gateway

Located in [`src/kimi_cli/acp/server.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/server.py), the `ACPServer` class listens for ACP client connections via stdio and manages the entire lifecycle of IDE interactions. It handles version negotiation, authentication challenges, session creation, loading, forking, and termination.

### ACPSession: Managing Agent State

The `ACPSession` class in [`src/kimi_cli/acp/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/session.py) represents a single Kimi session that an IDE interacts with. Each session maintains a `KimiSoul` instance, a model-ID converter, and unique turn-ID prefixes to ensure tool-call IDs remain unique across conversation turns.

### Protocol Version Negotiation

Before processing requests, the server ensures compatibility through `negotiate_version` in [`src/kimi_cli/acp/version.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/version.py). When an IDE sends `acp/initialize` with supported protocol versions, the server selects the best match via `ACPVersionSpec` and stores it in `self.negotiated_version`.

### Tool Integration via ACPTools

The `ACPTools` module in [`src/kimi_cli/acp/tools.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/tools.py) intercepts tool calls such as Shell or File operations. When the client supports richer UI elements like integrated terminals or diff viewers, the server routes tool execution to the IDE instead of using local implementations.

## How ACP Integration Works: The Communication Flow

1. **Server Initialization**: The IDE launches `kimi acp` (handled by [`src/kimi_cli/ui/acp/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/ui/acp/__init__.py)), which starts the server in single-session mode.

2. **Version Negotiation**: The client sends `acp/initialize` with supported protocol versions; the server responds with the negotiated version stored in `self.negotiated_version`.

3. **Authentication Check**: The server verifies login status. If unauthenticated, it returns an `AUTH_REQUIRED` error (`code -32000`) with available authentication methods.

4. **Session Creation**: The `new_session` method instantiates an `ACPSession` with a unique ID and initializes the Wire protocol layer.

5. **Prompt Processing**: The IDE calls `prompt` with `ACPContentBlock` objects (text, file references, or tool-call placeholders). The server converts these to Wire format (`acp.schema.TextContentBlock`, `acp.schema.ToolCallRequest`, etc.) and forwards them to the agent.

6. **Tool Execution Loop**: When the agent requests tools, `ACPTools` routes terminal-capable requests to the IDE's native UI if supported; otherwise, the server falls back to local execution. Recent releases fixed a regression where Shell tool output was not displayed in Zed.

7. **Persistence**: On shutdown, the server writes Wire log files. When `load_session` is called, the server replays these logs to restore full conversation history, enabling the "resume" functionality in supported clients.

## Zed IDE Configuration and Behavior

Zed communicates with Kimi through its native ACP client. According to [`src/kimi_cli/acp/AGENTS.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/AGENTS.md), Zed currently operates as a single-session client and does **not** invoke the `authenticate` method.

Configure Zed by adding the agent to `~/.config/zed/settings.json`:

```json
{
  "acp": {
    "agents": [
      {
        "id": "kimi",
        "name": "Kimi Code CLI",
        "command": "kimi acp"
      }
    ]
  }
}

```

Because Zed lacks external agent-server session management and skips the `authenticate` call, Kimi CLI treats Zed connections as isolated single-session contexts. Multi-session features like `list_sessions`, `fork_session`, and persistent session loading are disabled for Zed connections.

## JetBrains IDE Integration Features

JetBrains IDEs utilize the AI Chat plugin with an [`acp.json`](https://github.com/MoonshotAI/kimi-cli/blob/main/acp.json) configuration file (typically located at `~/.jetbrains/acp.json`). Unlike Zed, JetBrains clients fully implement the ACP specification including authentication and advanced session management.

Configure JetBrains with the following [`acp.json`](https://github.com/MoonshotAI/kimi-cli/blob/main/acp.json):

```json
{
  "agents": [
    {
      "id": "kimi",
      "command": "kimi acp",
      "displayName": "Kimi Code CLI"
    }
  ]
}

```

JetBrains supports the complete ACP feature set:

- **`authenticate`**: Handles token refresh flows and credential management (may be invoked for token refresh)
- **`list_sessions`**: Browse existing Kimi conversations in the AI Chat panel
- **`load_session`**: Resume previous conversations across IDE restarts via Wire log replay
- **`fork_session`**: Branch conversations to explore alternative solutions
- **`set_session_model`**: Switch between models (e.g., `gpt-4o-mini`) during active sessions by updating `config.default_model`

## Programmatic Session Control

For JetBrains-style integrations that support full session management, you can interact with the server programmatically:

```python
import acp
import asyncio

async def main():
    # Connect to the locally-started Kimi ACP server (STDIO)

    client = await acp.connect_stdio()
    
    # Negotiate the highest common protocol version

    await client.initialize(versions=[1, 2])
    
    # Switch models (JetBrains feature)

    await client.session.set_session_model(
        model_id="gpt-4o-mini",
        session_id="default"
    )
    
    # Send a prompt

    response = await client.session.prompt([
        acp.schema.TextContentBlock(type="text", text="Refactor this function")
    ])
    
    print("Assistant reply:", response.answer)
    await client.shutdown()

asyncio.run(main())

```

## Summary

- **ACP Server Architecture**: Kimi CLI's `ACPServer` and `ACPSession` classes in [`src/kimi_cli/acp/server.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/server.py) and [`src/kimi_cli/acp/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/session.py) translate ACP JSON-RPC to the internal Wire protocol.
- **IDE Compatibility**: Version negotiation via `negotiate_version` in [`src/kimi_cli/acp/version.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/version.py) ensures compatibility with both Zed and JetBrains clients.
- **Authentication Differences**: Zed skips authentication calls while JetBrains implements full credential management via the `authenticate` method.
- **Session Persistence**: Wire logs enable conversation history replay through `load_session`, supporting resume functionality in JetBrains and limited persistence in Zed.
- **Rich Tool Integration**: `ACPTools` in [`src/kimi_cli/acp/tools.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/tools.py) routes shell commands and file operations to IDE-native UI elements when available.

## Frequently Asked Questions

### What is the Agent Client Protocol (ACP) in Kimi CLI?

ACP is a JSON-RPC protocol that standardizes communication between AI agents and IDE clients. In Kimi CLI, the ACP server implementation in [`src/kimi_cli/acp/server.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/server.py) allows editors like Zed and JetBrains to launch and control Kimi agent sessions through a standardized interface, translating ACP messages into Kimi's internal Wire protocol.

### Why doesn't Zed show my existing Kimi sessions or support model switching?

Zed's current ACP client implementation does not call `list_sessions`, `load_session`, or `set_session_model`, treating each connection as an isolated single-session context. According to [`src/kimi_cli/acp/AGENTS.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/AGENTS.md), Zed lacks external agent-server session management and does not invoke the `authenticate` method, so Kimi CLI disables multi-session features for Zed while maintaining full session support for JetBrains IDEs.

### How do I switch AI models when using Kimi in JetBrains?

Call the `set_session_model` method with your desired model ID (e.g., `gpt-4o-mini`). The server updates its runtime configuration at `config.default_model` and persists the change for future sessions. This requires JetBrains' AI Chat plugin, which supports the full ACP session management protocol including model switching and session persistence.

### Where are conversation histories stored when using ACP integration?

Session histories are persisted as Wire log files written by the `ACPSession` class in [`src/kimi_cli/acp/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/acp/session.py) on shutdown. When `load_session` is called—typically by JetBrains IDEs on restart—the server replays these logs to restore the full conversation context. The storage location depends on Kimi CLI's configuration, typically within the user's home directory under Kimi's data path.