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.

​
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.

​
VS Code

VS Code does not have native ACP support, but a community extension is available. This extension is maintained by Omer Cohen and is not officially supported by OpenHands or Microsoft.
VS Code can connect to ACP-compatible agents through the VSCode ACP community extension. To configure OpenHands CLI with VS Code:
  1. Ensure OpenHands CLI is installed and configured (see Prerequisites)
  2. Open VS Code and go to Extensions (Cmd+Shift+X on Mac or Ctrl+Shift+X on Windows/Linux)
  3. Search for “VSCode ACP” and click Install
  4. Click the VSCode ACP icon in the Activity Bar (left sidebar)
  5. Click Connect to start a session
  6. Select OpenHands from the agent dropdown
  7. Start chatting with OpenHands!
The extension auto-detects installed agents by checking your system PATH. If OpenHands CLI is properly installed, it will appear in the agent dropdown automatically.

​
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.

​
Resuming Conversations

You can resume previous conversations when using OpenHands in ACP mode. This is useful when you want to continue working on a task from a previous session.

​
Finding Your Conversation ID

Since ACP mode doesn’t display an interactive conversation list, you need to first find your conversation ID using the standard CLI: 
openhands --resume
This displays a list of your recent conversations with their IDs: 
Recent Conversations:
--------------------------------------------------------------------------------
 1. abc123def456 (2h ago)
    Fix the login bug in auth.py

 2. xyz789ghi012 (yesterday)
    Add unit tests for the user service
--------------------------------------------------------------------------------
To resume a conversation, use: openhands --resume <conversation-id>

​
Resuming in ACP Mode

Once you have the conversation ID, you can resume it in ACP mode: 
openhands acp --resume <conversation-id>
For example, with Toad: 
toad acp "openhands acp --resume abc123def456"
Or in your Zed configuration: 
{
  "agent_servers": {
    "OpenHands (Resume)": {
      "command": "uvx",
      "args": [
        "openhands",
        "acp",
        "--resume",
        "abc123def456"
      ],
      "env": {}
    }
  }
}

​
Resuming the Latest Conversation

To resume your most recent conversation without looking up the ID: 
openhands acp --resume --last
The --resume flag without a conversation ID will display the conversation list and exit. This is useful for finding conversation IDs, but won’t start the ACP server. Always provide a conversation ID or use --last when starting ACP mode.

​
See Also