# IDE bridge

**Status: Next — not built.** This is a design note, not a description of
shipped behaviour.

This is now the main roadmap item. With chat in a terminal, the bridge is what
gives that session access to Nova: the selection, the open files, and diffs
rendered for review in the editor instead of as terminal text.

> Provenance: the protocol details below come from
> [coder/claudecode.nvim](https://github.com/coder/claudecode.nvim)'s
> `PROTOCOL.md`, which documents a working reimplementation of the same
> integration the VS Code extension uses. **None of it has been verified against
> the CLI by this project.** Treat every claim here as needing a first-run
> check. (The stdio protocol the extension used previously *was* verified; that
> work is in commit `89d1a06`.)

## What it would add

Nova becomes a **server** that the `claude` process running in your terminal
connects to, so that session can see the editor:

- the current selection and open files as context
- diffs pushed into Nova for review rather than rendered as terminal text
- "open this file at this line" from Claude

The extension already launches the terminal session (see
[launching](launching.md)); the bridge is the return path.

## How discovery works

1. Serve WebSocket on a random port, bound to loopback.
2. Write `~/.claude/ide/<port>.lock` (or `$CLAUDE_CONFIG_DIR/ide/`):

```json
{
  "pid": 1234,
  "workspaceFolders": ["/path/to/project"],
  "ideName": "Nova",
  "transport": "ws",
  "authToken": "<32-char lowercase hex, 128 bits from a CSPRNG>"
}
```

3. Export `CLAUDE_CODE_SSE_PORT=<port>` and `ENABLE_IDE_INTEGRATION=true` to the
   terminal where `claude` runs.
4. Claude connects and must present
   `x-claude-code-ide-authorization: <authToken>` during the handshake; the
   server validates it against the lock file.

Messages are JSON-RPC 2.0 over RFC 6455 WebSocket.

## MCP tools to implement

| Tool | Nova feasibility |
| --- | --- |
| `openFile` | ✅ `nova.workspace.openFile(uri, {line, column})` |
| `getCurrentSelection` | ✅ `activeTextEditor.selectedRange` |
| `getLatestSelection` | ✅ track via `onDidChangeSelection` |
| `getOpenEditors` | ✅ `nova.workspace.textEditors` |
| `getWorkspaceFolders` | ✅ `nova.workspace.path` |
| `checkDocumentDirty` | ✅ `document.isDirty` |
| `saveDocument` | ✅ `editor.save()` |
| `openDiff` | ⚠️ No diff viewer API. Reuse the editable-proposal pattern: stage the proposed file, open it, and map save → `FILE_SAVED`, close → `DIFF_REJECTED`. The tool blocks until one of those. Working code for this — including change reconstruction and a unified diff renderer — is in commit `89d1a06` (`Scripts/diff.js`, `Scripts/permissions.js`). |
| `close_tab` | ❌ Nova cannot close tabs programmatically |
| `closeAllDiffTabs` | ❌ same |
| `getDiagnostics` | ❌ An extension can only read its own `IssueCollection`. Claude running the linter itself via Bash is the workaround. |
| `executeCode` | ❌ No notebook/Jupyter API |

Returning a clear "unsupported" for the last four is fine — the VS Code
extension's surface is a superset of what any given editor can do.

## The Nova-shaped problem

**Nova's JS runtime has no WebSocket** (`fetch`, Streams, `TextEncoder` yes;
WebSocket no). So the server cannot live in the extension. It needs a **Node
sidecar** spawned via `Process`, with the extension and sidecar talking over
stdio — `Process` supports `stdio: "jsonrpc"`, which is a natural fit here since
the payloads are already JSON-RPC.

That means Node 18+ becomes a runtime requirement, which the extension has so
far avoided. Gate it behind a setting that is off by default.

```
Nova extension ──jsonrpc/stdio──> node sidecar ──ws──> claude (terminal)
      │                                │
      └─ Nova API (editors, selection) ┘   ~/.claude/ide/<port>.lock
```

## The terminal-tab angle

Nova has a built-in terminal, but **no extension API to create one or send text
to it** — commands can only be placed in the `editor`, `extensions`, `text` and
`command-palette` menus, and there is no terminal object in the API surface.

So the realistic shape is: the extension runs the sidecar and publishes the lock
file; you paste the launch command into Nova's terminal as you already do.
Discovery is automatic from there — the CLI finds the lock file without being
told. If the environment variables do not reach the terminal, `launch.js` can
prefix them onto the copied command.

If Panic ever exposes a terminal API, the only change is automating that last
step.

## Open questions

1. Does the CLI require the `ideName` to be on an allowlist, or is any string
   accepted?
2. What does it do with tools that answer "unsupported" — degrade, or error the
   turn?
3. With several terminal sessions open in one project, do they all attach to the
   same lock file — and does the editor need to distinguish them?
4. Lock-file lifecycle: who cleans up after a crash? (`pid` is in the file
   precisely so stale entries can be detected.)

## Effort

The WebSocket server, JSON-RPC plumbing, lock file and handshake are a
well-defined chunk; the tool implementations are mostly one-liners against the
Nova API. The risk is not the code — it is that the protocol is reverse
engineered and unversioned, so it can change under us. claudecode.nvim tracking
it successfully is good evidence it is stable enough in practice.