Skip to main content
This feature is experimental and may have limitations. Please report any issues you encounter on OpenHands-CLI repo.

​
Prerequisites

Before using OpenHands CLI with ACP, you must first install and configure the CLI:
  1. Install OpenHands CLI by following the CLI Mode installation instructions
  2. Configure your LLM settings using the /settings command
The ACP integration will reuse the credentials and configuration from your CLI settings.

​
What is the Agent Client Protocol (ACP)?

The Agent Client Protocol (ACP) is a standardized communication protocol that enables code editors and IDEs to interact with AI agents. ACP defines how clients (like code editors) and agents (like OpenHands) communicate through a JSON-RPC 2.0 interface. For more details about the protocol, see the ACP documentation.

​
ACP Integration

​
Toad

Toad is a universal terminal interface for AI agents, created by Will McGugan, the creator of the popular Python libraries Rich and Textual. The name comes from “textual code”—combining the Textual framework with coding assistance. Toad provides a modern terminal user experience that addresses several limitations common to existing terminal-based AI tools:
  • No flickering or visual artifacts - Toad can update partial regions of the screen without redrawing everything
  • Scrollback that works - You can scroll back through your conversation history and interact with previous outputs
  • A unified experience - Instead of learning different interfaces for different AI agents, Toad provides a consistent experience across all supported agents through ACP
OpenHands is included as a recommended agent in Toad’s agent store. Toad Terminal Interface

​
Installation

Install Toad using uv: 
uvx batrachian-toad
For more installation options and documentation, visit batrachian.ai.

​
Using OpenHands with Toad

  1. Open Toad’s agent store
  2. Find OpenHands in the list of recommended agents
  3. Click “Install” to set up OpenHands via uv tool install openhands --python 3.12 && openhands login
  4. Select OpenHands and start a conversation

​
Passing Command Line Arguments

You can launch Toad with specific OpenHands command line arguments by passing the full command: 
toad acp "openhands acp --llm-approve"
This allows you to use OpenHands CLI flags like --llm-approve for automatic LLM approval mode.
Some OpenHands CLI flags like --resume and --last are not yet supported in ACP mode. See this issue for updates.

​
Zed IDE

Zed is a high-performance code editor with built-in support for the Agent Client Protocol. To configure OpenHands CLI with Zed:
  1. Ensure OpenHands CLI is installed and configured (see Prerequisites)
  2. Open your Zed editor, use Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) to open the command palette, and search for agent: open settings
Zed Command Palette
  1. Then on the right side, click on + Add Agent and select Add Custom Agent
Zed Add Custom Agent
  1. Add the following to the "agent_servers" field:
{
  "agent_servers": {
    "OpenHands": {
      "command": "uvx",
      "args": [
        "openhands",
        "acp"
      ],
      "env": {}
    }
  }
}
  1. Save the file
  2. You can now use OpenHands within Zed!
Zed Use OpenHands Agent

​
Troubleshooting

If you encounter issues while using OpenHands in Zed with the ACP plugin, you can access detailed debug logs:
  1. Open the command palette with Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
  2. Type and select acp debug log to view detailed debug information
  3. Review the logs for any errors or warnings
  4. Restart a new conversation to reload connections after making configuration changes
The debug logs can help you identify configuration issues, connection problems, or errors in your setup.
If you encounter persistent issues, verify that OpenHands CLI is properly configured (see Prerequisites) and that all server commands are executable from your system PATH.

​
JetBrains IDEs

JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, etc.) support the Agent Client Protocol through JetBrains AI Assistant. To configure OpenHands CLI with JetBrains IDEs:
  1. Ensure OpenHands CLI is installed and configured (see Prerequisites)
  2. Find the full path to the openhands executable by running in your terminal: 
which openhands
  1. Create or edit the file $HOME/.jetbrains/acp.json and add the following configuration, replacing {full_path_to_openhands} with the actual full path from step 2:
{
  "agent_servers": {
    "OpenHands": {
      "command": "{full_path_to_openhands}",
      "args": ["acp"],
      "env": {}
    }
  }
}
For example, if which openhands returns /Users/username/.local/bin/openhands, your configuration should look like: 
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp"],
      "env": {}
    }
  }
}
  1. Follow the JetBrains ACP instructions to open and use an agent in your JetBrains IDE
Make sure you have JetBrains AI Assistant enabled in your IDE. The AI Assistant is available in JetBrains IDEs version 2024.3 or later.

​
See Also