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

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, 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 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. 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 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), 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, 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:

{
  "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 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:

{
  "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:

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 and 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 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 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 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, 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 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.

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