opencode-ui

Language: English | 简体中文

opencode-ui is a VS Code-compatible extension that brings an OpenCode chat interface into the IDE sidebar. It connects the extension host to the local or remote opencode CLI, starts opencode serve when needed, and renders sessions, streaming replies, tools, permissions, models, agents, todos, and image attachments in a React/Vite webview.

The extension is designed for VS Code and compatible IDEs such as Cursor.

Preview

Todo planning	Thinking details

Features

• Sidebar chat UI for OpenCode inside the IDE activity bar.
• Automatic opencode serve startup on 127.0.0.1, preferring port 4096 and falling back to a free port.
• Automatic opencode binary discovery across common Windows, Linux, WSL, and Remote-SSH install locations.
• Session listing, switching, export, deletion, timeline, undo, and redo.
• Model, provider, and agent selection with refresh support.
• Streaming transcript rendering for text, reasoning, tools, subtasks, todos, permission prompts, and question prompts.
• Temporary image/file prompt support with host-aware path normalization.
• Diagnostics popover and /debug support for self-checking sessions, models, agents, and request logs.

Requirements

• VS Code-compatible host with extension API >=1.105.0.
• Node.js >=20.0.0 and npm >=10.0.0 for development.
• opencode >=1.15.10 installed in the same host environment where the extension runs.

Check your CLI with:

opencode --version

Supported Hosts

You can override discovery with:

$env:OPENCODE_BINARY = "C:\path\to\opencode.exe"

or on Linux/WSL:

export OPENCODE_BINARY=/path/to/opencode

Install From Source

Install dependencies:

npm ci
npm --prefix webview-ui ci

Build and verify:

npm run check

Package a VSIX:

npm run package

Install the generated package into VS Code:

code --install-extension vsix/opencode-ui-vscode-0.0.78.vsix --force

Or into Cursor:

cursor --install-extension vsix/opencode-ui-vscode-0.0.78.vsix --force

Adjust the VSIX filename to match the current package.json version.

Development

Useful commands:

npm run build
npm --prefix webview-ui run build
npm run watch
npm --prefix webview-ui run dev
npm test
npm run test:extension

The practical preflight before opening a PR or building a release is:

npm run check

Run the VS Code smoke test when extension activation or packaged behavior changes:

npm run test:extension

Repository Layout

• src/extension.ts - extension activation, host detection, commands, and sidebar registration.
• src/bridge/ - opencode CLI wrappers, serve manager, compatibility checks, and parsers.
• src/shared/protocol.ts - typed webview/extension message contract.
• src/webview/SidebarProvider.ts - bridge between VS Code, opencode serve, CLI helpers, and the webview.
• webview-ui/ - React/Vite webview application.
• tests/ - Vitest coverage for parsers, host detection, serve startup, run streams, UI state helpers, and regressions.
• out/ and media/ - generated extension runtime artifacts included in the VSIX.
• vsix/ - local package output, ignored by git.

Do not hand-edit generated files in out/ or media/; rebuild them with npm run build.

CI

GitHub Actions runs the repository preflight and packages a VSIX artifact on pushes and pull requests:

npm run check
npm run package

Maintainers can publish the Marketplace package with the manual Publish Marketplace workflow after adding repository secrets named AZURE_CLIENT_ID and AZURE_TENANT_ID. The workflow signs in with GitHub Actions OIDC and prints the managed identity's Marketplace User Id in the run log and summary; add that User Id to the Visual Studio Marketplace publisher as a Contributor. The workflow rebuilds and verifies the project, generates the public VSIX from github-upload/release.json, uploads the VSIX artifact, and publishes it with vsce --azure-credential.

Feedback

Bug reports, host-specific setup notes, UI ideas, and feature requests are welcome. Please open an issue through GitHub Issues, and include your host environment, IDE, opencode --version, and any sanitized diagnostics that help reproduce the problem.

Troubleshooting

If the sidebar reports that opencode cannot be found:

• Run opencode --version in the same host where the extension runs.
• In Remote-WSL or Remote-SSH, install opencode in the remote environment, not only on Windows.
• Set OPENCODE_BINARY to an absolute executable path if your install location is unusual.
• Open the diagnostics popover in the sidebar and run the self-check.

If 4096 is occupied, the extension automatically starts opencode serve on another free port and caches that port per host kind.

Release Notes

Release notes can be published through GitHub releases or the VSIX artifact description.

License

MIT. See LICENSE.