Skip to main content
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:
  1. OpenHands CLI installed - See Installation
  2. LLM settings configured - Run openhands and use /settings
  3. JetBrains IDE version 2024.3 or later
  4. 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: Find the OpenHands Executable Path

In your terminal, run: 
which openhands
This returns the full path, for example:
  • Mac/Linux: /Users/username/.local/bin/openhands
  • Windows: C:\Users\username\.local\bin\openhands.exe
JetBrains requires the full absolute path to the executable. Using uvx or relative paths will not work.

​
Step 2: Create the ACP Configuration File

Create or edit the file $HOME/.jetbrains/acp.json: 
mkdir -p ~/.jetbrains
nano ~/.jetbrains/acp.json

​
Step 3: Add the Configuration

Add the following JSON, replacing {full_path_to_openhands} with the actual path from Step 1: 
{
  "agent_servers": {
    "OpenHands": {
      "command": "{full_path_to_openhands}",
      "args": ["acp"],
      "env": {}
    }
  }
}
Example (Mac/Linux): 
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp"],
      "env": {}
    }
  }
}
Example (Windows): 
{
  "agent_servers": {
    "OpenHands": {
      "command": "C:\\Users\\username\\.local\\bin\\openhands.exe",
      "args": ["acp"],
      "env": {}
    }
  }
}

​
Step 4: 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": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--llm-approve"],
      "env": {}
    }
  }
}

​
Auto-Approve Mode

For automatic approval of all actions (use with caution): 
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--always-approve"],
      "env": {}
    }
  }
}

​
Resume a Conversation

Resume a specific conversation: 
{
  "agent_servers": {
    "OpenHands (Resume)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--resume", "abc123def456"],
      "env": {}
    }
  }
}
Resume the latest conversation: 
{
  "agent_servers": {
    "OpenHands (Latest)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--resume", "--last"],
      "env": {}
    }
  }
}

​
Multiple Configurations

Add multiple configurations for different use cases: 
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp"],
      "env": {}
    },
    "OpenHands (Auto-Approve)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--always-approve"],
      "env": {}
    },
    "OpenHands (Resume Latest)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--resume", "--last"],
      "env": {}
    }
  }
}

​
Environment Variables

Pass environment variables to the agent: 
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp"],
      "env": {
        "LLM_API_KEY": "your-api-key"
      }
    }
  }
}

​
Troubleshooting

​
”Agent not found” or “Command failed”

  1. Verify the full path is correct: 
    which openhands
# Copy this exact path to your config
  2. Verify the path works: 
    /full/path/to/openhands --version
  3. Make sure you’re using the full absolute path, not uvx openhands

​
”AI Assistant not available”

  1. Ensure you have JetBrains IDE version 2024.3 or later
  2. Enable AI Assistant: Settings > Plugins > AI Assistant
  3. Restart the IDE after enabling

​
Agent doesn’t respond

  1. Check your LLM settings: 
    openhands
# Use /settings to configure
  2. Test ACP mode in terminal: 
    openhands acp
# Should start without errors

​
Configuration not applied

  1. Verify the config file location: ~/.jetbrains/acp.json
  2. Validate JSON syntax (no trailing commas, proper quotes)
  3. 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
--------------------------------------------------------------------------------

​
See Also