Fundamentals

Host Adapters

How OXP integrates with VS Code, Cursor, and other IDEs through host adapters.

A host adapter is a small module that bridges OXP into a specific IDE. It knows how to install, activate, render, and manage OXP extensions using that IDE's own APIs. The adapter is the only OXP-specific code an IDE needs.

Supported Hosts

Host	Status	Tier	Package
VS Code	✅ Shipped	L0	`@oxprotocol/host-vscode`
Cursor	✅ Works (VS Code fork)	L0	Same as VS Code
Windsurf	✅ Works (VS Code fork)	L0	Same as VS Code
VSCodium	✅ Works (VS Code fork)	L0	Same as VS Code
Piye IDE	🔄 In progress	L2 (native)	`hosts/piye/`
JetBrains	📋 Planned	—	—
Zed	📋 Planned	—	—
Theia	📋 Planned	—	—

The VS Code Host

The VS Code host adapter (hosts/vscode/) is a standard VS Code extension that:

Discovers installed OXP extensions from the shared store (~/.oxp/host-store/)
Activates them by instantiating the WASI component via the jco backend
Renders UI trees using @oxprotocol/ui/dom in a webview panel
Mediates host calls through the capability broker
Enforces CSP with per-render nonces (default-src 'none')

Commands

Command	Description
`OXP: Install Extension…`	Install from the registry
`OXP: Show Installed Extensions`	List installed OXP extensions
`OXP: Open Extension…`	Open an installed extension's panel
`OXP: Uninstall Extension…`	Remove an OXP extension
`OXP: Attach to Dev Server…`	Connect to `oxp dev` for hot-reload
`OXP: Reload Installed Extensions`	Re-scan and reload all

Settings

Setting	Default	Description
`oxp.registry`	`https://oxp.sh`	Registry base URL
`oxp.useSharedStore`	`true`	Use `~/.oxp/host-store/` so one `oxp install` works across all IDEs

The Shared Store

By default, oxp install places extensions in ~/.oxp/host-store/. Every host adapter reads from this directory. This means a single install command makes the extension available in VS Code, Cursor, Windsurf, and any other host on the machine.

The directory structure is:

~/.oxp/host-store/
└── @publisher/
    └── slug/
        └── 1.0.0/
            ├── oxp.json
            ├── ui/...
            └── .oxp/
                ├── integrity.json
                └── SIGNATURE

Integration Tiers

L0 — Sideload (works today)

The IDE does nothing special. OXP installs as a regular extension via the IDE's own CLI or extension directory. The VS Code adapter handles everything.

L1 — Registry Adapter

The IDE surfaces oxp.sh results in its built-in extension search. Users discover and install OXP extensions natively. The IDE calls the OXP resolve/install APIs behind the scenes.

L2 — Native Renderer

The IDE implements the @oxprotocol/ui component set in its native toolkit (e.g., GPUI for Zed, Swing for JetBrains). The same .oxp bundle gets 120fps native rendering without any webview overhead.

Building a Host Adapter

A host adapter needs to:

**Import @oxprotocol/host-core** for the install/verify/activate pipeline
**Import @oxprotocol/host-runtime** for the WASI component runtime
**Import @oxprotocol/ui/dom** (or implement native rendering) for UI
Wire the IDE's command palette, panel system, and settings to OXP's APIs
Provide storage, filesystem, and other host capabilities through the broker