How to Integrate kimi-cli with Your IDE Using the ACP Protocol

Yes, kimi-cli integrates with IDEs through its Agent Communication Protocol (ACP) server, enabling bidirectional communication between the MoonshotAI CLI and editor extensions like VS Code.

The MoonshotAI/kimi-cli repository transforms from a standalone terminal tool into a full IDE backend when launched in ACP mode. By leveraging the Agent Communication Protocol (ACP) architecture implemented across the src/kimi_cli/acp/ package, you can connect the CLI directly to your preferred editor for seamless file operations, tool execution, and agent interactions.

Understanding the ACP Server Architecture

The integration relies on a client-server model defined in src/kimi_cli/acp/server.py. When you launch the CLI with the ACP flag, it initializes an ACP server that listens for client connections—typically your IDE or a custom extension.

The server creates per-client sessions managed by src/kimi_cli/acp/session.py. Each session maintains state for tool calls, prompt responses, and conversation history. Before processing requests, the server negotiates protocol compatibility using the version logic in src/kimi_cli/acp/version.py to ensure the IDE client and CLI speak the same protocol revision.

For command execution, the server routes requests through src/kimi_cli/acp/kaos.py, which adapts the internal KAOS backend to the ACP interface. This allows your IDE to trigger shell commands, file searches, and other agent tools while the CLI handles the heavy lifting.

Starting the ACP Server

To begin integration, launch the CLI in ACP mode from your terminal:

$ kimi acp

# Alternative:

$ kimi-cli --acp

The entry point in src/kimi_cli/cli/__init__.py parses the --acp flag and initializes the server. You will see output indicating the server is waiting for client connections:

2024-07-26 12:00:00 INFO  Starting ACP server (single session) on stdio

The server now exposes methods for prompts, tool calls, and file operations that any ACP-compatible client can invoke.

VS Code Integration and File Operations

The CLI includes native support for opening files in your editor through the endpoint defined in src/kimi_cli/web/api/open_in.py. When the agent or an IDE extension requests to open a file, the CLI receives an OpenInRequest specifying the target application.

For VS Code on macOS, the implementation executes:

subprocess.run(["open", "-a", "Visual Studio Code", str(path)])

This same endpoint handles Sublime Text, iTerm, and Finder integrations. When using the official VS Code extension, clicking "Open in VS Code" from the chat pane sends a JSON payload over the ACP connection:

{
  "type": "open_in",
  "app": "vscode",
  "path": "/home/user/project/main.py",
  "is_file": true
}

The extension automatically manages the kimi acp subprocess lifecycle, connecting via stdio and forwarding these requests to the appropriate handler.

Building Custom IDE Extensions

If you use an editor without an official extension, you can write a minimal ACP client using the protocol definitions in src/kimi_cli/acp/. The client must connect to the running CLI and instantiate a session.

Here is a complete example for connecting to an existing TCP-based ACP server:

import asyncio
import acp
from kimi_cli.app import KimiCLI
from kimi_cli.acp.session import ACPSession

async def run():
    # Create the CLI instance (no UI)

    cli = KimiCLI.create()
    
    # Connect to the running ACP server via TCP

    conn = await acp.connect_tcp("127.0.0.1", 12345)
    
    # Initialize the session bridge

    session = ACPSession("my-session", cli, conn)
    
    # Send a prompt to the agent

    await session.prompt([
        acp.schema.TextContentBlock(type="text", text="Explain the repo.")
    ])

asyncio.run(run())

Alternatively, for local stdio connections (the standard for VS Code extensions), use acp.connect_stdio(). Your client will receive ToolCallRequest objects that you can map to your editor's native APIs, enabling two-way interaction where the CLI performs tasks and your editor displays results.

Summary

• kimi-cli integrates with IDEs via the Agent Communication Protocol (ACP) implemented in src/kimi_cli/acp/server.py and src/kimi_cli/acp/session.py.
• Launch the server using kimi acp or the --acp flag handled in src/kimi_cli/cli/__init__.py.
• File opening is managed by src/kimi_cli/web/api/open_in.py, which supports VS Code and other editors.
• Custom integrations are possible by implementing an ACP client that connects to the CLI and uses ACPSession for communication.
• The protocol includes version negotiation (version.py) and command adaptation (kaos.py) for reliable cross-editor compatibility.

Frequently Asked Questions

Does kimi-cli require the official VS Code extension to work with IDEs?

No. While an official VS Code extension provides the simplest setup, any editor that implements the Agent Communication Protocol can connect to the CLI. You can write a custom client using the acp package that spawns kimi-cli --acp and communicates over stdio or TCP sockets according to the protocol defined in src/kimi_cli/acp/.

What is the Agent Communication Protocol (ACP) in kimi-cli?

The ACP is a communication protocol that standardizes how the CLI exchanges prompts, tool calls, and results with external clients. It handles session management through ACPSession objects, version negotiation via src/kimi_cli/acp/version.py, and message routing through the server implementation in src/kimi_cli/acp/server.py.

How does the open-in feature work between kimi-cli and my editor?

When an agent or user requests to open a file, the request hits the open_in endpoint in src/kimi_cli/web/api/open_in.py. This module parses the request to determine the target editor (e.g., vscode), then executes the appropriate platform-specific command—such as open -a "Visual Studio Code" on macOS—to launch the file at the correct location.

Can I run multiple IDE connections to a single kimi-cli instance?

Yes. The architecture in src/kimi_cli/ui/acp/__init__.py supports multi-session ACP servers, allowing multiple IDE clients to connect simultaneously. Each connection receives its own session object managed by src/kimi_cli/acp/session.py, isolating tool calls and conversation state between different editor windows or users.

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