Skip to content

Simplify JetBrains ACP config and update version requirement #213

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
neubig wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Simplify JetBrains ACP config and update version requirement #213

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39c96e8
Simplify JetBrains ACP config and update version requirement
openhands-agent Dec 26, 2025
4480246
Merge main and apply JetBrains ACP simplifications to new location
openhands-agent Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 18 additions & 68 deletions openhands/usage/cli/ide/jetbrains.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Before configuring JetBrains IDEs:

1. **OpenHands CLI installed** - See [Installation](/openhands/usage/cli/installation)
2. **LLM settings configured** - Run `openhands` and use `/settings`
3. **JetBrains IDE version 2024.3 or later**
3. **JetBrains IDE version 25.3 or later**
4. **JetBrains AI Assistant enabled** in your IDE

<Note>
Expand All @@ -35,23 +35,7 @@ JetBrains AI Assistant is required for ACP support. Make sure it's enabled in yo

## Configuration

### Step 1: Find the OpenHands Executable Path

In your terminal, run:

```bash
which openhands
```

This returns the full path, for example:
- Mac/Linux: `/Users/username/.local/bin/openhands`
- Windows: `C:\Users\username\.local\bin\openhands.exe`

<Warning>
JetBrains requires the **full absolute path** to the executable. Using `uvx` or relative paths will not work.
</Warning>

### Step 2: Create the ACP Configuration File
### Step 1: Create the ACP Configuration File

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

Expand All @@ -67,51 +51,23 @@ Create or edit the file `$HOME/.jetbrains/acp.json`:
</Tab>
</Tabs>

### Step 3: Add the Configuration

Add the following JSON, replacing `{full_path_to_openhands}` with the actual path from Step 1:

```json
{
"agent_servers": {
"OpenHands": {
"command": "{full_path_to_openhands}",
"args": ["acp"],
"env": {}
}
}
}
```

**Example (Mac/Linux):**
### Step 2: Add the Configuration

```json
{
"agent_servers": {
"OpenHands": {
"command": "/Users/username/.local/bin/openhands",
"args": ["acp"],
"env": {}
}
}
}
```

**Example (Windows):**
Add the following JSON:

```json
{
"agent_servers": {
"OpenHands": {
"command": "C:\\Users\\username\\.local\\bin\\openhands.exe",
"command": "openhands",
"args": ["acp"],
"env": {}
}
}
}
```

### Step 4: Use OpenHands in Your IDE
### Step 3: Use OpenHands in Your IDE

Follow the [JetBrains ACP instructions](https://www.jetbrains.com/help/ai-assistant/acp.html) to open and use an agent in your JetBrains IDE.

Expand All @@ -125,7 +81,7 @@ For automatic LLM-based approval:
{
"agent_servers": {
"OpenHands": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--llm-approve"],
"env": {}
}
Expand All @@ -141,7 +97,7 @@ For automatic approval of all actions (use with caution):
{
"agent_servers": {
"OpenHands": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--always-approve"],
"env": {}
}
Expand All @@ -157,7 +113,7 @@ Resume a specific conversation:
{
"agent_servers": {
"OpenHands (Resume)": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--resume", "abc123def456"],
"env": {}
}
Expand All @@ -171,7 +127,7 @@ Resume the latest conversation:
{
"agent_servers": {
"OpenHands (Latest)": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--resume", "--last"],
"env": {}
}
Expand All @@ -187,17 +143,17 @@ Add multiple configurations for different use cases:
{
"agent_servers": {
"OpenHands": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp"],
"env": {}
},
"OpenHands (Auto-Approve)": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--always-approve"],
"env": {}
},
"OpenHands (Resume Latest)": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp", "--resume", "--last"],
"env": {}
}
Expand All @@ -213,7 +169,7 @@ Pass environment variables to the agent:
{
"agent_servers": {
"OpenHands": {
"command": "/Users/username/.local/bin/openhands",
"command": "openhands",
"args": ["acp"],
"env": {
"LLM_API_KEY": "your-api-key"
Expand All @@ -227,22 +183,16 @@ Pass environment variables to the agent:

### "Agent not found" or "Command failed"

1. Verify the full path is correct:
```bash
which openhands
# Copy this exact path to your config
```

2. Verify the path works:
1. Verify OpenHands CLI is installed:
```bash
/full/path/to/openhands --version
openhands --version
```

3. Make sure you're using the **full absolute path**, not `uvx openhands`
2. If the command is not found, ensure OpenHands CLI is in your PATH or reinstall it following the [Installation guide](/openhands/usage/cli/installation)

### "AI Assistant not available"

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

Expand Down