IDE Integration Overview

Use OpenHands directly in your favorite code editor through the Agent Client Protocol

IDE integration via ACP is experimental and may have limitations. Please report any issues on the OpenHands-CLI repo.

Windows Users: IDE integrations require the OpenHands CLI, which only runs on Linux, macOS, or Windows with WSL. Please install WSL and run your IDE from within WSL, or use a WSL-aware terminal configuration.

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.

Supported IDEs

IDE	Support Level	Setup Guide
Zed	Native	Built-in ACP support
Toad	Native	Universal terminal interface
VS Code	Community Extension	Via VSCode ACP extension
JetBrains	Native	IntelliJ, PyCharm, WebStorm, etc.

Prerequisites

Before using OpenHands with any IDE, you must:

1. Install OpenHands CLI following the installation instructions

2. Configure your LLM settings using the /settings command:

   openhands
   # Then use /settings to configure
   

The ACP integration will reuse the credentials and configuration from your CLI settings stored in ~/.openhands/settings.json.

How It Works

1. Your IDE launches openhands acp as a subprocess
2. Communication happens via JSON-RPC 2.0 over stdio
3. OpenHands uses your configured LLM and runtime settings
4. Results are displayed in your IDE’s interface

The ACP Command

The openhands acp command starts OpenHands as an ACP server:

# Basic ACP server
openhands acp

# With LLM-based approval
openhands acp --llm-approve

# Resume a conversation
openhands acp --resume <conversation-id>

# Resume the latest conversation
openhands acp --resume --last

ACP Options

Option	Description
--resume [ID]	Resume a conversation by ID
--last	Resume the most recent conversation
--always-approve	Auto-approve all actions
--llm-approve	Use LLM-based security analyzer
--streaming	Enable token-by-token streaming

Confirmation Modes

OpenHands ACP supports three confirmation modes to control how agent actions are approved:

Always Ask (Default)

The agent will request user confirmation before executing each tool call or prompt turn. This provides maximum control and safety.

openhands acp  # defaults to always-ask mode

Always Approve

The agent will automatically approve all actions without asking for confirmation. Use this mode when you trust the agent to make decisions autonomously.

openhands acp --always-approve

LLM-Based Approval

The agent uses an LLM-based security analyzer to evaluate each action. Only actions predicted to be high-risk will require user confirmation, while low-risk actions are automatically approved.

openhands acp --llm-approve

Changing Modes During a Session

You can change the confirmation mode during an active session using slash commands:

Command	Description
/confirm always-ask	Switch to always-ask mode
/confirm always-approve	Switch to always-approve mode
/confirm llm-approve	Switch to LLM-based approval mode
/help	Show all available slash commands

The confirmation mode setting persists for the duration of the session but will reset to the default (or command-line specified mode) when you start a new session.

Choosing an IDE

Zed

High-performance editor with native ACP support. Best for speed and simplicity.

Toad

Universal terminal interface. Works with any terminal, consistent experience.

VS Code

Popular editor with community extension. Great for VS Code users.

JetBrains

IntelliJ, PyCharm, WebStorm, etc. Best for JetBrains ecosystem users.

Resuming Conversations in IDEs

You can resume previous conversations in ACP mode. Since ACP mode doesn’t display an interactive list, first find your conversation ID:

openhands --resume

This shows your recent conversations:

Recent Conversations:
--------------------------------------------------------------------------------
 1. abc123def456 (2h ago)
    Fix the login bug in auth.py

 2. xyz789ghi012 (yesterday)
    Add unit tests for the user service
--------------------------------------------------------------------------------

Then configure your IDE to use --resume <id> or --resume --last. See each IDE’s documentation for specific configuration.

See Also

• ACP Documentation - Full protocol specification
• Terminal Mode - Use OpenHands in the terminal
• Resume Conversations - Detailed resume guide