# JetBrains IDEs

> Configure OpenHands with IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs

[JetBrains IDEs](https://www.jetbrains.com/) 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](/openhands/usage/cli/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

<Note>
  JetBrains AI Assistant is required for ACP support. Make sure it's enabled in your IDE.
</Note>

## Configuration

### Step 1: Find the OpenHands Executable Path

In your terminal, run:

```bash  theme={null}
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

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

<Tabs>
  <Tab title="Mac/Linux">
    ```bash  theme={null}
    mkdir -p ~/.jetbrains
    nano ~/.jetbrains/acp.json
    ```
  </Tab>

  <Tab title="Windows">
    Create the file at `C:\Users\<username>\.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  theme={null}
{
  "agent_servers": {
    "OpenHands": {
      "command": "{full_path_to_openhands}",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

**Example (Mac/Linux):**

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

**Example (Windows):**

```json  theme={null}
{
  "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](https://www.jetbrains.com/help/ai-assistant/acp.html) to open and use an agent in your JetBrains IDE.

## Advanced Configuration

### LLM-Approve Mode

For automatic LLM-based approval:

```json  theme={null}
{
  "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):

```json  theme={null}
{
  "agent_servers": {
    "OpenHands": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--always-approve"],
      "env": {}
    }
  }
}
```

### Resume a Conversation

Resume a specific conversation:

```json  theme={null}
{
  "agent_servers": {
    "OpenHands (Resume)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--resume", "abc123def456"],
      "env": {}
    }
  }
}
```

Resume the latest conversation:

```json  theme={null}
{
  "agent_servers": {
    "OpenHands (Latest)": {
      "command": "/Users/username/.local/bin/openhands",
      "args": ["acp", "--resume", "--last"],
      "env": {}
    }
  }
}
```

### Multiple Configurations

Add multiple configurations for different use cases:

```json  theme={null}
{
  "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:

```json  theme={null}
{
  "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:
   ```bash  theme={null}
   which openhands
   # Copy this exact path to your config
   ```

2. Verify the path works:
   ```bash  theme={null}
   /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:
   ```bash  theme={null}
   openhands
   # Use /settings to configure
   ```

2. Test ACP mode in terminal:
   ```bash  theme={null}
   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:

```bash  theme={null}
openhands --resume
```

This displays recent conversations with their IDs:

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

## See Also

* [IDE Integration Overview](/openhands/usage/cli/ide/overview) - ACP concepts and other IDEs
* [JetBrains ACP Documentation](https://www.jetbrains.com/help/ai-assistant/acp.html) - Official JetBrains ACP guide
* [Resume Conversations](/openhands/usage/cli/resume) - Find conversation IDs


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.openhands.dev/llms.txt