VS Code

Use OpenHands in Visual Studio Code with the VSCode ACP community extension

VS Code can connect to ACP-compatible agents through the VSCode ACP community extension.

VS Code does not have native ACP support. This extension is maintained by Omer Cohen and is not officially supported by OpenHands or Microsoft.

Prerequisites

Before configuring VS Code:

1. OpenHands CLI installed - See Installation
2. LLM settings configured - Run openhands and use /settings
3. VS Code - Download from code.visualstudio.com

Installation

Step 1: Install the Extension

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X on Mac or Ctrl+Shift+X on Windows/Linux)
3. Search for “VSCode ACP”
4. Click Install

Or install directly from the VS Code Marketplace.

Step 2: Connect to OpenHands

1. Click the VSCode ACP icon in the Activity Bar (left sidebar)
2. Click Connect to start a session
3. Select OpenHands from the agent dropdown
4. Start chatting with OpenHands!

How It Works

The VSCode ACP extension auto-detects installed agents by checking your system PATH. If OpenHands CLI is properly installed, it will appear in the agent dropdown automatically.

The extension runs openhands acp as a subprocess and communicates via the Agent Client Protocol.

Verification

Ensure OpenHands is discoverable:

which openhands
# Should return a path like /Users/you/.local/bin/openhands

If the command is not found, install OpenHands CLI:

uv tool install openhands --python 3.12

Advanced Usage

Custom Arguments

The VSCode ACP extension may support custom launch arguments. Check the extension’s settings for options to pass flags like --llm-approve.

Resume Conversations

To resume a conversation, you may need to:

1. Find your conversation ID: openhands --resume
2. Configure the extension to use custom arguments (if supported)
3. Or use the terminal directly: openhands acp --resume <id>

The VSCode ACP extension’s feature set depends on the extension maintainer. Check the extension documentation for the latest capabilities.

Troubleshooting

OpenHands Not Appearing in Dropdown

1. Verify OpenHands is installed and in PATH:

   which openhands
   openhands --version
   

2. Restart VS Code after installing OpenHands

3. Check if the extension recognizes agents:

   • Look for any error messages in the extension panel
   • Check the VS Code Developer Tools (Help > Toggle Developer Tools)

Connection Failed

1. Ensure your LLM settings are configured:

   openhands
   # Use /settings to configure
   

2. Check that openhands acp works in terminal:

   openhands acp
   # Should start without errors (Ctrl+C to exit)
   

Extension Not Working

1. Update to the latest version of the extension
2. Check for VS Code updates
3. Report issues on the extension’s GitHub

Limitations

Since this is a community extension:

• Feature availability may vary
• Support depends on the extension maintainer
• Not all OpenHands CLI flags may be accessible through the UI

For the most control over OpenHands, consider using:

• Terminal Mode - Direct CLI usage
• Zed - Native ACP support

See Also

• IDE Integration Overview - ACP concepts and other IDEs
• VSCode ACP Extension - Extension marketplace page
• Terminal Mode - Use OpenHands in terminal