# IDE Integration

CodeBuddy Code supports two integration methods with editors, both at the same level of IDE integration capabilities:

1. Using the ACP (Agent Client Protocol) as a universal "Agent Server" called by IDEs
2. Using the `--ide` startup parameter and `/ide` slash command as an "IDE plugin backend companion process" for deep integration

## Integration Method 1: ACP Protocol Integration

Suitable for editors that support ACP, such as Zed, using CodeBuddy Code as a universal Agent Server.

### Supported Editors

#### Zed Editor

Full integration via ACP protocol, supporting:

- Project context awareness
- Tool operation delegation (file read/write, terminal commands)
- Permission request interaction
- Real-time streaming responses

For configuration details, see: [ACP Protocol Integration Documentation](./acp.md)

## Integration Method 2: IDE Plugin Integration (`--ide` / `/ide`)

Suitable for VS Code / Cursor / Windsurf / JetBrains series IDEs, integrated through plugin + local MCP server. The IDE-side plugin is responsible for:

- Creating and maintaining MCP connections (SSE / WebSocket)
- Passing workspace information, selections, and other context to CodeBuddy via MCP protocol
- Exposing IDE capabilities like `openFile` / `openDiff` / `getDiagnostics` / `close_tab` for CodeBuddy to call

### `--ide` Startup Parameter

When you start CodeBuddy directly in the terminal, you can use the `--ide` parameter to have the CLI actively try to connect to the IDE corresponding to the current working directory:

```bash
codebuddy --ide
```

Behavior description:

- CodeBuddy will scan lock files created by IDE plugins in the current user directory to detect available IDE instances
- Only considers an IDE as "valid" if its workspace contains the current directory
- Auto-connection only happens when **exactly one** valid IDE matches the current working directory; if zero or multiple match, auto-connection is silently skipped, and you can use `/ide` to manually select
- Stale lock files for IDE processes that have already exited are cleaned up before detection, avoiding connections to invalid ports
- After successful connection, the CLI will obtain from the IDE MCP server:
  - File/diff preview (openFile / openDiff)
  - Diagnostic information (getDiagnostics)
  - Selection change notifications (selection_changed)

> `--ide` is just a quick connection method when "you manually start the CLI from an IDE terminal" and is not responsible for actually starting the IDE or plugin.

### `/ide` Slash Command

When using IDE plugin integration in CodeBuddy's interactive interface, you can use the `/ide` command to view and manage the current IDE connection status:

```text
/ide
```

Typical uses include:

- Viewing whether an IDE is currently connected and which one
- Selecting which instance to connect to when multiple available IDEs exist
- Manually disconnecting or re-establishing MCP connections with the IDE

The specific interaction behavior is determined by the IDE integration UI, but the overall positioning is "managing IDE integration status" rather than directly initiating chat.

## Which Integration Method to Choose?

- If your editor natively supports ACP (such as Zed), we recommend using **ACP Protocol Integration**:
  - Start with `codebuddy --acp`
  - The editor is responsible for session UI and tool delegation
- If you use VS Code / Cursor / JetBrains, etc., and install the CodeBuddy plugin from the plugin marketplace, we recommend using **`--ide` / `/ide` Plugin Integration**:
  - The plugin is responsible for starting the CodeBuddy process and establishing MCP connections
  - The CLI side establishes and manages connections with the IDE through `--ide` / `/ide`

Both methods are equivalent at the "integration level" - they both allow CodeBuddy to deeply collaborate with the IDE as an external Agent, just with different access protocols and UI carriers.

## Future Plans

Future versions will provide more enhanced features:

- Friendlier DIFF display and modification confirmation process (combined with IDE diff preview)
- Richer context selection and visualization in IDE plugins
- More official integrations with editors and IDEs

## Related Documentation

- [ACP Protocol Integration](./acp.md) - Detailed ACP configuration guide
- [CLI Reference Manual](./cli-reference.md) - Command-line parameter descriptions
- [Slash Commands](./slash-commands.md) - Overview of session commands including `/ide`
