# IDE Integrations

Run Droid from VS Code, Cursor, Windsurf, JetBrains IDEs, Zed, or any editor terminal.

Droid works in any editor with an integrated terminal. For deeper editor context, use the dedicated integrations for VS Code-family editors, JetBrains IDEs, or Zed.

## Supported editors

<ComparisonTable label='Supported editors'>

| Editor | Setup | Context and capabilities |
| ------ | ----- | ------------------------ |
| **VS Code, Cursor, Windsurf** | Run `droid` in the integrated terminal or install the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Factory.factory-vscode-extension). | Shares active file, selection, open files, diagnostics, and IDE-native diff/file actions. |
| **JetBrains IDEs** | Install **Factory Droid** from JetBrains AI Agents or configure ACP manually. | Runs Droid inside JetBrains AI Chat with model and autonomy controls. |
| **Zed** | Install the Factory Droid extension or configure a custom ACP agent. | Runs Droid in Zed Agent Panel, supports `@`-tagged file context, and can use Zed MCP context servers. |
| **Other editors** | Run `droid` from the integrated terminal. | Uses normal CLI behavior. Reference files by path or paste context manually. |

</ComparisonTable>

## VS Code, Cursor, and Windsurf

Open your editor's integrated terminal and run:

```bash
droid
```

Droid detects VS Code-family terminals and can install or update the Factory extension automatically. You can also install it directly from the Marketplace.

The extension gives Droid:

- Active file path and selection.
- Open file list.
- Diagnostics from the editor.
- IDE-native diff viewing.
- File-opening actions from Droid responses.

Use `/ide` inside Droid to inspect, install, update, or disconnect the integration:

```text
/ide
```

## JetBrains IDEs

JetBrains IDEs use the Agent Client Protocol (ACP). Use this path for IntelliJ IDEA, PyCharm, WebStorm, Android Studio, GoLand, PhpStorm, RubyMine, DataGrip, Rider, and other JetBrains IDEs.

### Install from JetBrains AI Agents

In any JetBrains IDE (2025.3+) with JetBrains AI:

1. Open **Settings → Tools → AI Assistant → Agents**, or choose **Install From ACP Registry...** from the agent picker.
2. Find **Factory Droid** and click **Install**.
3. Open the AI Chat panel.
4. Select **Factory Droid** from the agent dropdown.
5. If prompted, complete the browser login flow and confirm the device code.

### Configure manually

Install the Droid CLI first with <code>curl -fsSL https://app.factory.ai/cli | sh</code>.

Then edit `~/.jetbrains/acp.json`:

```json
{
  "agent_servers": {
    "Factory Droid": {
      "command": "/path/to/droid",
      "args": ["exec", "--output-format", "acp"]
    }
  }
}
```

To authenticate with an API key instead of browser login, add `FACTORY_API_KEY`:

```json
{
  "agent_servers": {
    "Factory Droid": {
      "command": "/path/to/droid",
      "args": ["exec", "--output-format", "acp"],
      "env": {
        "FACTORY_API_KEY": "your_api_key"
      }
    }
  }
}
```

<Note>
  Account creation, billing, and API key management happen in the Factory App, not inside JetBrains.
</Note>

After setup, open **View → Tool Windows → AI Assistant**, start a new chat, and choose **Factory Droid**. JetBrains handles session history from the AI Chat panel. The JetBrains integration is currently a rich ACP chat front-end; it does not yet share open files, selections, diagnostics, or IDE-native Droid diffs automatically.

## Zed

Zed also uses ACP. The quickest setup is to install the Factory Droid extension, open the Agent Panel, click **+**, and choose **Factory Droid**.

To configure Droid manually, install the CLI, then edit `~/.config/zed/settings.json`:

```json
{
  "agent_servers": {
    "Factory Droid": {
      "type": "custom",
      "command": "/path/to/droid",
      "args": ["exec", "--output-format", "acp"]
    }
  }
}
```

For API key authentication:

```json
{
  "agent_servers": {
    "Factory Droid": {
      "type": "custom",
      "command": "/path/to/droid",
      "args": ["exec", "--output-format", "acp"],
      "env": {
        "FACTORY_API_KEY": "$FACTORY_API_KEY"
      }
    }
  }
}
```

Open the Agent Panel with <Kbd keys='Cmd+?' /> on macOS or <Kbd keys='Ctrl+?' /> on Linux and Windows, then start a new chat with Factory Droid.

Zed does not restore past Factory Droid sessions from the Agent Panel. For longer work, keep the panel open or start a new chat with a short recap. Use Zed's `@`-tagging to add file context:

```text
Refactor the state management in @src/components/TodoList.tsx to use a reducer instead of multiple useState hooks.
```

### Add MCP servers in Zed

Zed's `context_servers` can expose MCP tools to Droid. For example:

```json
{
  "context_servers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools@latest"]
    }
  }
}
```

## Settings

Set `ideAutoConnect` when you want Droid to reconnect to the most recent compatible IDE even from an external terminal:

```json
{
  "ideAutoConnect": true
}
```

When `ideAutoConnect` is off, Droid only auto-connects from a detected IDE terminal. See [Settings](/droid-cli/settings) for the full configuration reference.

## Troubleshooting

<Troubleshooting>
  <TroubleshootingItem title="VS Code extension does not install">
    - Run `droid` from the editor's integrated terminal.
    - Make sure the matching shell command is available: `code` for VS Code, `cursor` for Cursor, or `surf` / `windsurf` for Windsurf.
    - If the command is missing, open the Command Palette and run the editor's **Shell Command: Install ... command in PATH** action.
    - Confirm the editor is allowed to install extensions.
  </TroubleshootingItem>

  <TroubleshootingItem title="JetBrains or Zed cannot start Factory Droid">
    - Run `droid exec --output-format acp` in a regular terminal to confirm the CLI and authentication work.
    - Check that the `command` path points to the Droid binary.
    - Check that `args` includes `exec` and `--output-format acp`.
    - If using API key auth, confirm `FACTORY_API_KEY` is available to the IDE process.
    - Windows on ARM is not supported.
  </TroubleshootingItem>

  <TroubleshootingItem title="Esc does not interrupt Droid in a JetBrains terminal">
    In JetBrains settings, go to **Tools → Terminal**. Disable **Move focus to the editor with Escape**, or remove the **Switch focus to Editor** terminal keybinding.
  </TroubleshootingItem>

  <TroubleshootingItem title="Editor integration disabled">
    Verify the VS Code extension is installed, then run `/ide` to inspect connection state.
  </TroubleshootingItem>

  <TroubleshootingItem title="Missing file context">
    Save files first. Unsaved buffers over 500 KB are skipped for performance.
  </TroubleshootingItem>

  <TroubleshootingItem title="Stale diagnostics">
    Refresh diagnostics from the VS Code Command Palette.
  </TroubleshootingItem>

  <TroubleshootingItem title="Terminal closes immediately">
    Check shell startup scripts and make sure they do not auto-exit.
  </TroubleshootingItem>

  <TroubleshootingItem title="Network blocked by proxy">
    Configure proxy settings or set `HTTP_PROXY` / `HTTPS_PROXY`.
  </TroubleshootingItem>

  <TroubleshootingItem title="MCP server fails in Zed">
    Run the same `command` and `args` outside Zed to debug environment or dependency issues.
  </TroubleshootingItem>

  <TroubleshootingItem title="Issue persists">
    Contact [support@factory.ai](mailto:support@factory.ai) with logs from `~/.factory/logs/`.
  </TroubleshootingItem>
</Troubleshooting>

<RelatedLinks>
  <RelatedLink href='/autonomy-and-safety/specification-mode' title='Use Specification Mode'>
    When editor context should feed a reviewed implementation plan.
  </RelatedLink>
  <RelatedLink href='/harness/mcp' title='Connect MCP tools'>
    Expose editor-hosted context servers and other external systems.
  </RelatedLink>
</RelatedLinks>