pi-lovely-ide

Connect Pi to your IDE. Pi sees what you have selected in the editor, and you can send it code ranges and diagnostics with a keystroke — no copy-pasting file paths, line numbers, or compiler errors into the prompt.

The integration has two halves:

• @xl0/pi-lovely-ide (this package) — a Pi extension that discovers IDE servers, maintains the connection, and turns IDE events into model context.
• Pi Lovely IDE (xl0.pi-lovely-ide) — a VS Code extension that publishes editor state over the Pi IDE Protocol. Lives in this repo under ide-plugins/vscode, distributed separately through the Marketplace.

What you get

• Selection context — Pi's footer live-tracks your cursor and selection. When you submit a prompt, the current selection (with a bounded excerpt of the selected text) is attached as context, so "why is this wrong?" just works.
• Mentions — Alt+Shift+L in VS Code pastes an @file#range reference into Pi's input. The model gets the referenced code alongside your prompt.
• Problems attachments — Alt+Shift+D pastes a [problems: …] marker carrying the diagnostics under your selection (or the whole file; a separate command attaches all workspace Problems). The model sees the diagnostics and the selected code they belong to.
• Notebook support — selections, mentions, and Problems in notebook cells carry the cell id/index and cell-relative line numbers.
• /ide — selector and live preview: pick an IDE endpoint or open scoped settings for auto-connect, auto-reconnect, selection context/history, context-message display, debug logging of raw IDE events, and the selected-text line budget.

Setup

1. Install the VS Code extension: search for Pi Lovely IDE in the Marketplace, or

   code --install-extension xl0.pi-lovely-ide
   

2. Install the Pi package:

   pi install npm:@xl0/pi-lovely-ide
   

   Or load it for a single session without installing:

   pi -e npm:@xl0/pi-lovely-ide
   

3. Start Pi in a folder that is (or is inside) a workspace folder open in VS Code. Pi auto-connects on startup; if it doesn't, run /ide and pick the endpoint. The footer shows ● IDE with the IDE name once connected.

Settings support User (~/.pi/agent/xl0-lovely-ide.json) and Workspace (<workspace>/.pi/xl0-lovely-ide.json) scopes. Workspace values override User values.

How it works

Each VS Code window runs a small WebSocket server on localhost and advertises it through a lockfile. Pi discovers lockfiles, picks the server whose workspace matches its own working directory, and connects.

  VS Code window                                     Pi session
┌──────────────────────────┐                   ┌──────────────────────────┐
│ Pi Lovely IDE extension  │                   │ @xl0/pi-lovely-ide       │
│                          │    selection      │                          │
│ WebSocket server         │    mention        │ footer status            │
│ on 127.0.0.1:<port> ─────┼──── diagnostics ─▶│ @refs and [problems]     │
│        │                 │     events        │ model context            │
└────────┼─────────────────┘                   └────────────▲─────────────┘
         │ writes                                           │
         ▼                                    discovers and │ connects
  ~/.pi/ide/<port>.lock   ──────────────────────────────────┘
  (protocol, port, token, workspaces, PID)

Discovery and auth. The lockfile carries the protocol version, port, a random per-server token, and the window's workspace folders. Pi only accepts a lockfile when the protocol/version match, the advertised process is alive, and Pi's cwd equals or descends from one of the workspace roots. The connection is authenticated with the token and starts with a hello handshake declaring which events Pi wants (selection, mention, diagnostics). Everything stays on localhost.

From event to model context. Selection events only update Pi's footer and a pending snapshot — nothing reaches the model until you submit a prompt. Mention and Problems events paste a plain-text reference into Pi's input; the rich context (referenced code, diagnostics, selected lines) is attached only if that reference is still present in the prompt you actually submit. Delete the marker and nothing extra is sent. If you mention a range explicitly, the ambient selection is skipped for that prompt so the model doesn't get the same code twice.

Context is injected as <selection>, <mention>, and <problems> blocks appended to your message, and the bookkeeping markers are stripped from what the model sees. Aggregate Problems context is capped at Pi's standard output limit; when it overflows, the full text is written to a private temp file and the model gets the path.

By default, ambient selection context remains on earlier messages, keeping prompt-cache prefixes stable at the cost of retaining those input tokens. Disable Keep past selection context in /ide settings to keep only the latest available ambient selection block; that block remains until a newer selection replaces it.

Protocol docs

• PI_IDE_PROTOCOL.md — canonical pi-native protocol.
• CC_IDE_PROTOCOL.md — historical Claude Code IDE protocol reference only.

Development

Pi package:

bun install
bun run check
pi -e .

VS Code plugin (ide-plugins/vscode):

cd ide-plugins/vscode
bun install
bun run compile

Debug from this repo with VS Code's Run VS Code Extension launch config. It compiles the plugin, opens an Extension Development Host, starts a local Pi IDE Protocol server, and writes ~/.pi/ide/<port>.lock. To package and install the plugin into your regular VS Code (or another CLI such as cursor):

./dev-install-vscode-plugin.sh [ide-cli]

Manual smoke test:

1. Launch Run VS Code Extension.
2. In the Extension Development Host, open a project folder.
3. Run Pi in the same project with this package loaded: pi -e ..
4. Use /ide if auto-connect did not connect.
5. Select text in VS Code; Pi footer should show the file/range.
6. Run Pi: Mention Selection; Pi input should receive @file#x-y.
7. Run Pi: Attach Problems; Pi input should receive [problems: path#line-range].

Related projects

---

Like this work? Hire me