How the ACP Server Facilitates IDE Integration with Zed and JetBrains

The ACP (Agent-Control-Protocol) server acts as a WebSocket bridge that enables external editors like Zed and JetBrains IDEs to communicate with the Kimi CLI agent, handling session lifecycle, authentication, model selection, and file system synchronization through a standardized protocol interface.

The ACP server is the core infrastructure component in the MoonshotAI/kimi-cli repository that transforms the Kimi command-line agent into a language model assistant accessible directly within integrated development environments. By implementing the Agent-Control-Protocol, this server abstracts the complexity of agent management into discrete RPC endpoints that any compatible editor can consume.

Core Protocol: How the ACP Server Bridges Editors and Kimi

When an editor launches an ACP client, it connects to the server via a WebSocket-compatible acp.Client. The server implementation in src/kimi_cli/acp/server.py manages the entire lifecycle of this connection through several distinct phases.

Version Negotiation and Initialization

The server first validates protocol compatibility through version negotiation. The ACPServer.initialize method calls negotiate_version to align the client’s protocol version with the CLI’s supported version range. This ensures that editors running different client versions can safely communicate with the Kimi agent without protocol mismatches.

Session Lifecycle Management

Once initialized, the server creates isolated execution contexts via new_session, load_session, and resume_session. These methods spin up a dedicated KimiCLI instance, attach the editor’s working directory as the session context, and return a unique session ID to the client. According to the source in src/kimi_cli/acp/server.py (lines 50-73), this architecture allows multiple IDE windows to maintain separate conversations with the agent while sharing the same server process.

Authentication and Model Exposure

The ACP server handles credential management through a terminal-auth delegation pattern. Rather than implementing OAuth flows directly within the editor, the server builds an authentication description that triggers the terminal-based kimi login flow. This implementation in src/kimi_cli/acp/server.py (lines 77-95) allows editors to initiate authentication without handling API keys directly.

For model selection, the server exposes available LLM configurations via _expand_llm_models. This method returns the complete list of configured models, including "thinking" variants, enabling the editor UI to present users with a dropdown of available intelligence modes. The server stores these configurations in src/kimi_cli/acp/server.py (lines 41-60) and serves them to any connected client during the initialization handshake.

Filesystem Synchronization and Tool Routing

The ACPKaos class in src/kimi_cli/acp/kaos.py implements the critical bridge between the agent's file operations and the editor's buffer state. By exposing fs.readTextFile and fs.writeTextFile methods, the server proxies all filesystem interactions back to the IDE. This keeps the editor’s representation of the codebase synchronized with the agent’s view, allowing diffs to render in-place rather than through external file watchers.

Tool execution follows a capability-advertisement pattern defined in src/kimi_cli/acp/tools.py. When a client advertises the terminal capability, the server swaps built-in tools like Shell and Terminal for ACP-backed counterparts. Approval requests for dangerous operations become session/request_permission messages that the IDE surfaces to users through native UI dialogs, as documented in src/kimi_cli/acp/AGENTS.md (lines 66-73).

Editor-Specific Implementation Details

While the ACP protocol is generic, current editor integrations exhibit specific behaviors based on client capabilities.

Zed Editor Integration

The Zed editor ships with a native ACP client that connects to the Kimi server but currently does not invoke the authenticate method. Instead, it relies on the terminal login flow for credential management. Additionally, because Zed’s external-agent server does not yet implement session persistence, the session/load RPC defined in src/kimi_cli/acp/AGENTS.md (lines 89-93) remains unexercised in practice, with each connection creating a fresh session.

JetBrains IDE Integration

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm) can embed ACP clients using the same connection logic. While the repository does not contain a dedicated JetBrains plugin, these editors can consume the standard ACP endpoints (new_session, prompt, cancel) through the protocol implementation in src/kimi_cli/acp/types.py. A JetBrains integration would follow the identical flow: connecting to the server, retrieving available commands and models, and forwarding filesystem operations through the ACP channel rather than direct disk access.

Practical Implementation: Code Examples

The following patterns demonstrate how editors interact with the ACP server using the protocol methods defined in the source:

Create a new session with specific working directory and MCP server configuration:

await acp_server.new_session(
    cwd="/path/to/project",
    mcp_servers=[MCPServer(url="http://localhost:8000")],
)

Send prompts and receive completions through the established session:

response = await acp_server.prompt(
    prompt=[ACPContentBlock(text="Explain this function")],
    session_id="abc123",
)

print(response.completion)  # LLM answer rendered in IDE panel

Switch between model variants, including reasoning modes:

await acp_server.set_session_model(
    model_id="gpt-4,thinking",
    session_id="abc123",
)

Perform atomic file edits via the ACP-backed filesystem abstraction:

await acp_server.ext_method(
    method="fs/writeTextFile",
    params={"path": "src/module.py", "content": "print('hello')"},
)

Summary

• The ACP server in src/kimi_cli/acp/server.py provides a WebSocket-based bridge between the Kimi CLI and external editors through standardized RPC endpoints.
• Session management methods (new_session, load_session, resume_session) isolate agent contexts while allowing editors to specify working directories and MCP server configurations.
• Authentication is delegated to terminal flows via the login command, avoiding the need for editors to handle API credentials directly.
• Filesystem operations are proxied through ACPKaos implementations, keeping editor buffers synchronized with agent modifications.
• Both Zed and JetBrains editors consume the same protocol endpoints, though Zed currently operates without session persistence and explicit authentication calls.

Frequently Asked Questions

What protocol does the ACP server use to communicate with editors?

The ACP server uses the Agent-Control-Protocol (ACP) over WebSocket connections. Clients instantiate an acp.Client that negotiates protocol versions via ACPServer.initialize before exchanging JSON-RPC messages for session management, prompting, and tool execution.

How does the ACP server handle authentication for IDE clients?

Rather than implementing OAuth within the editor, the server registers a terminal-auth description that triggers the kimi login flow in the integrated terminal. The server builds this authentication configuration in src/kimi_cli/acp/server.py (lines 77-95), allowing editors to initiate login without handling API keys.

Can the ACP server integrate with editors other than Zed and JetBrains?

Yes. Any editor implementing the ACP client specification can connect to the server. The protocol defines standard endpoints for session lifecycle, model selection, and file operations in src/kimi_cli/acp/types.py, making the Kimi agent accessible to VS Code, Vim, Emacs, or custom editors that implement the WebSocket client and capability advertisement handshake.

How are file system operations kept in sync between Kimi and the IDE?

The ACPKaos class in src/kimi_cli/acp/kaos.py implements fs.readTextFile and fs.writeTextFile methods that proxy all agent file operations through the ACP channel. When the agent modifies a file, the operation routes through the editor's buffer rather than direct disk writes, ensuring the IDE's state remains synchronized and enabling inline diff visualization.

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