JetBrains IDEs - OpenHands Docs

JetBrains IDEs support the Agent Client Protocol through JetBrains AI Assistant.

Supported IDEs

This guide applies to all JetBrains IDEs:

IntelliJ IDEA
PyCharm
WebStorm
GoLand
Rider
CLion
PhpStorm
RubyMine
DataGrip
And other JetBrains IDEs

Prerequisites

Before configuring JetBrains IDEs:

OpenHands CLI installed - See Installation
LLM settings configured - Run openhands and use /settings
JetBrains IDE version 25.3 or later
JetBrains AI Assistant enabled in your IDE

JetBrains AI Assistant is required for ACP support. Make sure it’s enabled in your IDE.

Configuration

Step 1: Create the ACP Configuration File

Create or edit the file $HOME/.jetbrains/acp.json:

Mac/Linux
Windows

mkdir -p ~/.jetbrains
nano ~/.jetbrains/acp.json

Create the file at C:\Users\<username>\.jetbrains\acp.json

Step 2: Add the Configuration

Add the following JSON:

{
  "agent_servers": {
    "OpenHands": {
      "command": "openhands",
      "args": ["acp"],
      "env": {}
    }
  }
}

Step 3: Use OpenHands in Your IDE

Follow the JetBrains ACP instructions to open and use an agent in your JetBrains IDE.

Advanced Configuration

LLM-Approve Mode

For automatic LLM-based approval:

{
  "agent_servers": {
    "OpenHands": {
      "command": "openhands",
      "args": ["acp", "--llm-approve"],
      "env": {}
    }
  }
}

Auto-Approve Mode

For automatic approval of all actions (use with caution):

{
  "agent_servers": {
    "OpenHands": {
      "command": "openhands",
      "args": ["acp", "--always-approve"],
      "env": {}
    }
  }
}

Resume a Conversation

Resume a specific conversation:

{
  "agent_servers": {
    "OpenHands (Resume)": {
      "command": "openhands",
      "args": ["acp", "--resume", "abc123def456"],
      "env": {}
    }
  }
}

Resume the latest conversation:

{
  "agent_servers": {
    "OpenHands (Latest)": {
      "command": "openhands",
      "args": ["acp", "--resume", "--last"],
      "env": {}
    }
  }
}

Multiple Configurations

Add multiple configurations for different use cases:

{
  "agent_servers": {
    "OpenHands": {
      "command": "openhands",
      "args": ["acp"],
      "env": {}
    },
    "OpenHands (Auto-Approve)": {
      "command": "openhands",
      "args": ["acp", "--always-approve"],
      "env": {}
    },
    "OpenHands (Resume Latest)": {
      "command": "openhands",
      "args": ["acp", "--resume", "--last"],
      "env": {}
    }
  }
}

Environment Variables

Pass environment variables to the agent:

{
  "agent_servers": {
    "OpenHands": {
      "command": "openhands",
      "args": ["acp"],
      "env": {
        "LLM_API_KEY": "your-api-key"
      }
    }
  }
}

Troubleshooting

”Agent not found” or “Command failed”

Verify OpenHands CLI is installed:
openhands --version
If the command is not found, ensure OpenHands CLI is in your PATH or reinstall it following the Installation guide

”AI Assistant not available”

Ensure you have JetBrains IDE version 25.3 or later
Enable AI Assistant: Settings > Plugins > AI Assistant
Restart the IDE after enabling

Agent doesn’t respond

Check your LLM settings:
openhands # Use /settings to configure

Test ACP mode in terminal:

openhands acp
# Should start without errors

Configuration not applied

Verify the config file location: ~/.jetbrains/acp.json
Validate JSON syntax (no trailing commas, proper quotes)
Restart your JetBrains IDE

Finding Your Conversation ID

To resume conversations, first find the ID:

openhands --resume

This displays recent conversations with their IDs:

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

​Supported IDEs

​Prerequisites

​Configuration

​Step 1: Create the ACP Configuration File

​Step 2: Add the Configuration

​Step 3: Use OpenHands in Your IDE

​Advanced Configuration

​LLM-Approve Mode

​Auto-Approve Mode

​Resume a Conversation

​Multiple Configurations

​Environment Variables

​Troubleshooting

​”Agent not found” or “Command failed”

​”AI Assistant not available”

​Agent doesn’t respond

​Configuration not applied

​Finding Your Conversation ID

​See Also

Supported IDEs

Prerequisites

Configuration

Step 1: Create the ACP Configuration File

Step 2: Add the Configuration

Step 3: Use OpenHands in Your IDE

Advanced Configuration

LLM-Approve Mode

Auto-Approve Mode

Resume a Conversation

Multiple Configurations

Environment Variables

Troubleshooting

”Agent not found” or “Command failed”

”AI Assistant not available”

Agent doesn’t respond

Configuration not applied

Finding Your Conversation ID

See Also