Skip to content

acp-mode.md

Latest commit

 

History

History
178 lines (131 loc) · 6.41 KB

acp-mode.md

File metadata and controls

178 lines (131 loc) · 6.41 KB

ACP Mode

ACP (Agent Client Protocol) mode is a special operational mode of Gemini CLI designed for programmatic control, primarily for IDE and other developer tool integrations. It uses a JSON-RPC protocol over stdio to communicate between Gemini CLI agent and a client.

To start Gemini CLI in ACP mode, use the --acp flag:

gemini --acp

Agent Client Protocol (ACP)

ACP is an open protocol that standardizes how AI coding agents communicate with code editors and IDEs. It addresses the challenge of fragmented distribution, where agents traditionally needed custom integrations for each client. With ACP, developers can implement their agent once, and it becomes compatible with any ACP-compliant editor.

For a comprehensive introduction to ACP, including its architecture and benefits, refer to the official ACP Introduction documentation.

Existing integrations using ACP

The ACP Agent Registry simplifies the distribution and management of ACP-compatible agents across various IDEs. Gemini CLI is an ACP-compatible agent and can be found in this registry.

For more general information about the registry, and how to use it with specific IDEs like JetBrains and Zed, refer to the IDE Integration documentation.

You can also find more information on the official ACP Agent Registry page.

Architecture and protocol basics

ACP mode establishes a client-server relationship between your tool (the client) and Gemini CLI (the server).

  • Communication: The entire communication happens over standard input/output (stdio) using the JSON-RPC 2.0 protocol.
  • Client's role: The client is responsible for sending requests (e.g., prompts) and handling responses and notifications from Gemini CLI.
  • Gemini CLI's role: In ACP mode, Gemini CLI listens for incoming JSON-RPC requests, processes them, and sends back responses.

The core of the ACP implementation can be found in packages/cli/src/acp/acpClient.ts.

Host input extensions

ACP covers prompts, cancellations, permissions, and session control. Gemini CLI also exposes a Gemini-specific ACP extension for structured host input so an ACP client can surface questions in its own UI instead of handing control back to the terminal.

During initialize, Gemini CLI advertises the extension in agentCapabilities._meta.geminiCli.hostInput:

{
  "version": 1,
  "requestUserInput": true,
  "method": "gemini/requestUserInput",
  "supportedKinds": ["ask_user", "exit_plan_mode"]
}

To enable host input, the ACP client must advertise clientCapabilities._meta.geminiCli.hostInput with requestUserInput: true. The client can also narrow support by setting supportedKinds.

  • Include ask_user to let Gemini CLI surface ask_user tool requests over ACP.
  • Include exit_plan_mode to let Gemini CLI surface plan-approval questions over ACP.
  • Omit ask_user if you want to keep ask_user disabled in ACP mode while still supporting other host-input request kinds.

If the client doesn't opt in, Gemini CLI keeps ask_user excluded in ACP mode. This preserves the default ACP behavior and avoids opening host-driven dialogs unless the client has explicitly implemented them.

When Gemini CLI needs host input, it calls gemini/requestUserInput as an ACP extension request. The request includes:

  • sessionId for the active ACP session
  • requestId for the host-input interaction
  • kind, such as ask_user or exit_plan_mode
  • title and questions
  • optional extraParts
  • optional toolCall metadata

The client responds with either:

  • {"outcome":"submitted","answers":{"0":"..."}}
  • {"outcome":"cancelled"}

This extension is separate from MCP. Use it when you want Gemini CLI to keep owning the tool flow while your ACP host owns the user-facing input surface.

Extending with MCP

ACP can be used with the Model Context Protocol (MCP). This lets an ACP client (like an IDE) expose its own functionality as "tools" that the Gemini model can use.

  1. The client implements an MCP server that advertises its tools.
  2. During the ACP initialize handshake, the client provides the connection details for its MCP server.
  3. Gemini CLI connects to the MCP server, discovers the available tools, and makes them available to the AI model.
  4. When the model decides to use one of these tools, Gemini CLI sends a tool call request to the MCP server.

This mechanism lets for a powerful, two-way integration where the agent can leverage the IDE's capabilities to perform tasks. The MCP client logic is in packages/core/src/tools/mcp-client.ts.

Capabilities and supported methods

The ACP protocol exposes a number of methods for ACP clients (e.g. IDEs) to control Gemini CLI.

Core methods

  • initialize: Establishes the initial connection and lets the client to register its MCP server and negotiate Gemini-specific ACP extensions.
  • authenticate: Authenticates the user.
  • newSession: Starts a new chat session.
  • loadSession: Loads a previous session.
  • prompt: Sends a prompt to the agent.
  • cancel: Cancels an ongoing prompt.

Session control

  • setSessionMode: Allows changing the approval level for tool calls (e.g., to auto-approve).
  • unstable_setSessionModel: Changes the model for the current session.

File system proxy

ACP includes a proxied file system service. This means that when the agent needs to read or write files, it does so through the ACP client. This is a security feature that ensures the agent only has access to the files that the client (and by extension, the user) has explicitly allowed.

Debugging and telemetry

You can get insights into the ACP communication and the agent's behavior through debugging logs and telemetry.

Debugging logs

To enable general debugging logs, start Gemini CLI with the --debug flag:

gemini --acp --debug

Telemetry

For more detailed telemetry, you can use the following environment variables to capture telemetry data to a file:

  • GEMINI_TELEMETRY_ENABLED=true
  • GEMINI_TELEMETRY_TARGET=local
  • GEMINI_TELEMETRY_OUTFILE=/path/to/your/log.json

This will write a JSON log file containing detailed information about all the events happening within the agent, including ACP requests and responses. The integration test integration-tests/acp-telemetry.test.ts provides a working example of how to set this up.