# intellij

Connect Pi to IntelliJ's integrated MCP server only when explicitly requested.
Starting Pi performs no IntelliJ work and exposes no IntelliJ tools.

## Setup

In IntelliJ, open **Settings | Tools | MCP Server | Manual Client Configuration** and click **Copy HTTP Stream Config**.
Copy its loopback HTTP URL, then connect once:

```text
/intellij connect http://127.0.0.1:PORT/ENDPOINT
```

The URL is saved under `intellij.url` in Pi's global `settings.json` only after IntelliJ identifies itself, the project resolves, and its exposed-tool catalog loads.
Later sessions can use `/intellij connect`.

## Settings

| Key | Type | Default |
| --- | --- | --- |
| `intellij.url` | string | none |

There is no env var or flag.
Precedence: trusted project `.pi/settings.json`, then user `~/.pi/agent/settings.json`, then none.
Project settings are read only when Pi trusts the project.
A project URL lets one project target its own IntelliJ instance.
Connecting through a project URL leaves the user settings untouched; only user or explicit URLs are saved globally.
A non-string value never falls back to a lower source.
`/intellij connect` and `/intellij reconnect` warn and do not connect; `/intellij status` reports the endpoint as unavailable with the error.

If Pi must open the current project, `idea` must be on `PATH`.
Create it with **Tools | Create Command-line Launcher** in IntelliJ.

## Commands

- `/intellij connect [url]` connects, opens `ctx.cwd` when necessary, and activates IntelliJ's exposed tools.
- `/intellij disconnect` closes this session's MCP client and deactivates only IntelliJ tools.
- `/intellij reconnect` refreshes the saved endpoint and catalog without launching IntelliJ.
- `/intellij status` reports state, endpoint, project, and active tool count without connecting.
- `/intellij tools` reports the last fetched catalog without connecting.

Remote tools are registered with an `intellij_` prefix.
The bridge hides `projectPath` from agent-facing schemas and injects the Pi session's exact `ctx.cwd`.
The footer shows IntelliJ connection health as ` …`, ` ✓`, or ` ✗`.
Collapsed tool rows show operation, target, and outcome; expand them for diagnostics, matches, patches, and full returned context.
IntelliJ's **Exposed Tools** setting is the only allowlist.

See [PLAN.md](PLAN.md) for the binding specification.

## Debug

Opt in through [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `command.run.start`, `command.run.finish`, `command.run.error`, `runtime.shutdown.start`, `runtime.shutdown.finish`, `runtime.shutdown.error`.