OpenCode UI for VS Code
A OpenCode GUI for VS Code.
OpenCode GUI brings the OpenCode coding agent directly into Visual Studio Code with streaming chat, code context, file and image attachments, implementation plans, subagent tracking, session history, and live quota monitoring.
It is built for developers who use OpenCode but want a smoother IDE workflow instead of switching between the terminal and editor.
If this extension helps your workflow, consider giving the repo a star.
Demo
Main Conversation Flow
Interactive Plan Viewer
Requirements
This extension requires the OpenCode CLI to be installed locally.
curl -fsSL https://opencode.ai/install | bash
You can also install OpenCode with a package manager such as:
brew install anomalyco/tap/opencode
or:
npm i -g opencode-ai@latest
[!IMPORTANT]
Disclaimer: This extension is an independent personal project and is not affiliated with, endorsed by, or maintained by OpenCode or its creators.
Why Install This
If you already use OpenCode in the terminal, this extension gives you a more integrated VS Code workflow.
- Use OpenCode inside a dedicated VS Code sidebar
- Chat with the OpenCode coding agent without leaving your editor
- Attach files, images, and selected code directly into the chat
- Generate and review
implementation_plan.md files before code changes
- Answer inline planning questions from the agent
- Add annotations and comments to implementation plans
- Track agent-generated todos and active tasks
- View subagent activity, tool calls, and execution progress
- Monitor live quota usage for GitHub Copilot, Z.ai, OpenAI, and other supported providers
- Keep persistent session history across VS Code restarts
- Use slash-command skills, MCP status, LSP status, and agent panels from one UI
Key Features
OpenCode CLI UI inside VS Code
OpenCode UI wraps your local OpenCode runtime with a native VS Code experience. It talks to the OpenCode server through @opencode-ai/sdk, streams events over SSE, and renders the workflow inside a React-powered webview.
This gives you the power of OpenCode while keeping your planning, prompting, reviewing, and coding flow inside VS Code.
Streaming AI Chat
- Real-time streaming responses
- Markdown rendering with syntax highlighting
- Collapsible reasoning/thinking sections
- Copy message content to clipboard
- Inline image previews
- Unified error cards for API failures and timeout issues
- Token usage tracking for prompt, response, reasoning, and cache activity
Code Context and Attachments
- Attach highlighted code selections from the editor
- Insert file references directly into the chat input
- Attach images through paste or drag-and-drop
- Ground prompts with files, screenshots, code snippets, and project context
- Use keyboard shortcuts for fast file and code context insertion
Implementation Plan Workflow
- Generate structured
implementation_plan.md files before code changes
- Review implementation plans in a dedicated plan viewer
- Add annotations and comments before execution
- Track checklist progress
- Request revisions before switching to build mode
- Keep planning, review, and execution connected in the same workflow
Interactive Questions
- The agent can ask clarification questions inline
- Supports selectable quick answers
- Supports custom answers
- Helps the Plan agent gather missing requirements before generating or revising a plan
- Preserves interactive context across session reloads
Subagent Tracking
- Track active background subagents
- View subagent status, progress, thinking events, and tool calls
- Inspect subagent details in a modal
- See subagent cards inside assistant messages
- Understand what the agent is doing while work is in progress
Agent Task Tracking
- View agent-generated todos and tasks
- Keep track of what the agent thinks still needs to be done
- See active work beside quotas, MCP status, LSP status, skills, and agent panels
Session History
- Persistent chat sessions across VS Code restarts
- Rename, delete, and fork sessions
- Keep long-running work organized
- Automatically compact sessions when context usage gets too high
- Continue working without losing important context
Quota and Budget Monitoring
Live quota status is available for:
- OpenAI
- GitHub Copilot
- Z.ai
- Google Gemini
- Zhipu
- Other supported providers exposed by OpenCode
The quota panel helps you see provider usage, limits, and daily budget signals directly inside VS Code.
MCP, LSP, Skills, and Agents
The right sidebar can show:
- MCP server status
- MCP tool lists
- LSP server status
- Slash-command skills
- Available OpenCode agents
- Agent mode, color, and description
- Active tasks and quota state
Plugin Ecosystem Support
OpenCode UI works with OpenCode plugin-driven workflows, including community plugin collections like Oh My OpenCode.
Plugin-provided agents, skills, and capabilities can be surfaced directly inside the extension UI.
Screenshots
Conversation View
Full chat flow with streaming responses, structured outputs, and session continuity.
Plan Builder and Annotations
Plan workflow from generation to review, including comments and annotations before execution.
Attachments and Code Context
Attach file references and highlighted code lines directly in the chat box.
Tasks, Subagents, and Side Panels
Agent-generated tasks, subagent activity, and side-panel visibility for active execution state.
Quota and Interactive Questions
Interactive question flow with selectable answers, custom responses, and live quota visibility.
Quick Start
Install the OpenCode CLI:
curl -fsSL https://opencode.ai/install | bash
Install this extension in VS Code.
Open the OpenCode panel from the Activity Bar.
Start a new session and send your first prompt.
Usage
Opening the Chat Panel
| Action |
Shortcut |
| Focus / open chat |
Ctrl+Esc / Cmd+Esc |
| New session |
Ctrl+Shift+Esc / Cmd+Shift+Esc |
| Send selected code |
Ctrl+L / Cmd+L |
| Insert file reference |
Ctrl+Alt+K / Cmd+Alt+K |
You can also open the panel from the Activity Bar using the OpenCode icon.
Sending a Message
Type your prompt in the chat input and press Enter.
Use Shift+Enter for a new line.
You can:
- Attach images by pasting or dragging them into the input
- Reference files with
Ctrl+Alt+K / Cmd+Alt+K
- Attach selected code with
Ctrl+L / Cmd+L
- Use slash commands by typing
/
- Select an agent from the agent dropdown
- Switch between Plan, Build, and custom agents exposed by OpenCode
Plan Mode
- Select the Plan agent from the agent dropdown.
- Describe the feature or change you want.
- Answer any inline questions from the agent.
- OpenCode generates an
implementation_plan.md.
- Click View Implementation Plan.
- Review the plan.
- Add annotations or comments.
- Request revisions if needed.
- Switch to Build mode or proceed with implementation.
Managing Sessions
- Click the history icon in the chat header to open the session list.
- Sessions are listed with title, date, and token count.
- Use the session menu to rename, delete, or fork a session.
Stopping a Response
Click the Stop button in the chat header to abort the current AI request.
Configuration
Access settings through:
File → Preferences → Settings → OpenCode
or add them to settings.json.
Server Settings
| Setting |
Type |
Default |
Description |
opencode.serverPort |
number |
0 |
Port for the OpenCode server. 0 auto-assigns a free port. |
opencode.autoStart |
boolean |
true |
Start the server automatically when the extension activates. |
opencode.persistSessions |
boolean |
true |
Persist chat sessions across VS Code restarts. |
opencode.autoCompact |
boolean |
true |
Compact a session automatically when context usage nears the threshold. |
opencode.autoCompactThreshold |
number |
0.9 |
Fraction of model context usage that triggers auto-compaction. |
opencode.requestTimeout |
number |
120000 |
Request timeout in milliseconds. |
opencode.complexQueryMultiplier |
number |
1.5 |
Timeout multiplier for prompts with heavier context. |
Logging Settings
| Setting |
Type |
Default |
Description |
opencode.logging.level |
string |
"info" |
Minimum log level: error, warn, info, debug. |
opencode.logging.enableConsole |
boolean |
true |
Write logs to the VS Code Output channel. |
opencode.logging.enableFile |
boolean |
false |
Write logs to a rotating file on disk. |
opencode.logging.maxFileSize |
number |
5242880 |
Max log file size in bytes before rotation. |
opencode.logging.maxFiles |
number |
3 |
Number of backup log files to keep. |
Example settings.json
{
"opencode.serverPort": 0,
"opencode.autoStart": true,
"opencode.persistSessions": true,
"opencode.autoCompact": true,
"opencode.autoCompactThreshold": 0.9,
"opencode.requestTimeout": 120000,
"opencode.logging.level": "debug",
"opencode.logging.enableFile": true
}
Architecture
┌─────────────────────────────────────────────────────────────┐
│ VS Code Extension Host │
│ │
│ extension.ts │
│ ├── OpencodeServerManager (manages local OpenCode server)│
│ ├── SessionService (persistence + sync) │
│ ├── StatusBarProvider (connection indicator) │
│ ├── ChatViewProvider (main webview host) │
│ ├── PlanViewProvider (implementation plan viewer) │
│ └── DiffReviewProvider (VCS diff panel) │
│ │
│ Services │
│ ├── MessageStreamService (SSE event streaming) │
│ ├── SubagentTracker (background task tracking) │
│ ├── QuotaService (provider quota polling) │
│ ├── RequestBudgeter (daily budget calculation) │
│ ├── PlanParser (implementation_plan.md) │
│ └── GeminiTokenUsageTracker │
└────────────────────┬────────────────────────────────────────┘
│ HTTP + SSE via @opencode-ai/sdk
│ port: auto-assigned or configured
┌────────────────────▼────────────────────────────────────────┐
│ OpenCode Local Server │
│ accessed via @opencode-ai/sdk │
│ │
│ REST API │
│ GET /agent — list agents │
│ GET /command — list slash-command skills │
│ GET /mcp — MCP server status │
│ GET /lsp/status — LSP server status │
│ GET /event — SSE event stream │
│ POST /session/:id/prompt — send message │
│ ...and more session, file, tool, and VCS endpoints │
└─────────────────────────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ Webview React UI │
│ webview/shared/dist/chat.js │
│ │
│ ChatShell.tsx — layout container │
│ MessageComponents.tsx — user and assistant messages │
│ PanelComponents.tsx — sidebar panels │
│ StreamingComponents.tsx — live streaming card │
│ BudgetIndicator.tsx — inline budget banner │
│ SubagentDetailModal.tsx — subagent inspection modal │
└─────────────────────────────────────────────────────────────┘
Data Flow
- User types in the chat input.
- The webview sends a
sendPrompt message to the extension host.
ChatViewProvider receives the message.- The extension calls
client.session.prompt().
MessageStreamService streams SSE events from the OpenCode server.- Events are forwarded to the webview.
- The React reducer updates the UI in real time.
Project Structure
vscode-opencode/
├── src/
│ ├── extension.ts
│ ├── providers/
│ │ ├── ChatViewProvider.ts
│ │ ├── DiffReviewProvider.ts
│ │ ├── PlanViewProvider.ts
│ │ └── StatusBarProvider.ts
│ ├── services/
│ │ ├── OpencodeServerManager.ts
│ │ ├── SessionService.ts
│ │ ├── MessageStreamService.ts
│ │ ├── SubagentTracker.ts
│ │ ├── QuotaService.ts
│ │ ├── RequestBudgeter.ts
│ │ ├── PlanParser.ts
│ │ └── GeminiTokenUsageTracker.ts
│ ├── shared/
│ ├── types/
│ └── utils/
│ └── Logger.ts
├── webview/
│ └── shared/
│ ├── src/
│ │ ├── chat/
│ │ │ ├── ChatShell.tsx
│ │ │ ├── MessageComponents.tsx
│ │ │ ├── PanelComponents.tsx
│ │ │ ├── StreamingComponents.tsx
│ │ │ ├── BudgetIndicator.tsx
│ │ │ ├── SubagentDetailModal.tsx
│ │ │ ├── ImagePreviewModal.tsx
│ │ │ └── lib/
│ │ │ ├── store.ts
│ │ │ ├── types.ts
│ │ │ ├── messageHandler.ts
│ │ │ ├── structuredOutputValidator.ts
│ │ │ └── generated/
│ │ ├── plan/
│ │ ├── diff-review/
│ │ └── components/ui/
│ └── dist/
├── scripts/
├── tests/
├── resources/
├── AGENTS.md
├── LOGGING.md
├── package.json
├── tsconfig.json
└── esbuild.config.js
Core Services
OpencodeServerManager
Starts and manages the local OpenCode server process.
Handles:
- Dynamic port allocation
- Server readiness detection
- Cross-platform process cleanup
- Automatic reconnection
- Status events for the status bar and chat provider
MessageStreamService
Custom fetch-based SSE client for OpenCode events.
Handles:
- SSE line parsing
- Chunk-boundary buffering
- Request cancellation
- Subscriber management
- Auto-reconnect with back-off
SessionService
Persists sessions between VS Code restarts using context.globalState.
It also syncs with the server on startup and reconciles sessions created externally.
SubagentTracker
Parses subagent-related events and builds parent-child session relationships.
It exposes subagent summaries and details to the webview.
QuotaService
Polls provider-specific quota APIs.
Supported providers include:
- OpenAI
- GitHub Copilot
- Google Gemini
- Zhipu
- Z.ai
RequestBudgeter
Calculates daily request allowance based on monthly quota and days remaining in the billing cycle.
Stores usage data under:
~/.opencode/budget/
PlanParser
Parses implementation_plan.md files.
Extracts:
- Goal
- Description
- File operations
- Verification steps
- Checklist items
- Completion state
Webview React UI
The webview is a standalone React application bundled into:
webview/shared/dist/chat.js
webview/shared/dist/chat.css
It communicates with the extension host through:
vscode.postMessage(...)
window.addEventListener("message", ...)
Main UI Files
| File |
Purpose |
ChatShell.tsx |
Main layout container |
MessageComponents.tsx |
User and assistant messages |
PanelComponents.tsx |
Sidebar panels |
StreamingComponents.tsx |
Live streaming card |
BudgetIndicator.tsx |
Inline quota and budget banner |
SubagentDetailModal.tsx |
Subagent inspection modal |
Message Protocol
| Direction |
Type |
Purpose |
| Extension → Webview |
initState |
Initial state on panel open |
| Extension → Webview |
streamEvent |
SSE event chunk |
| Extension → Webview |
mcpStatus |
MCP server status |
| Extension → Webview |
lspStatus |
LSP server status |
| Extension → Webview |
agentsList |
Available agents |
| Extension → Webview |
commandsList |
Available slash commands |
| Extension → Webview |
quotaData |
Provider quota data |
| Extension → Webview |
budgetInfo |
Daily budget data |
| Webview → Extension |
sendPrompt |
Send a user prompt |
| Webview → Extension |
getMcpStatus |
Request MCP status |
| Webview → Extension |
getLspStatus |
Request LSP status |
| Webview → Extension |
getAgents |
Request agents |
| Webview → Extension |
stopRequest |
Stop active request |
| Webview → Extension |
newSession |
Create new session |
Development
Install Dependencies
npm install
Build
npm run build
Run in VS Code
Press F5 to launch an Extension Development Host.
Watch Mode
Use two terminals:
npm run watch
npm run webview:watch
During development:
- Extension code is rebuilt by esbuild.
- Webview code is rebuilt separately.
- Reload the Extension Host with
Ctrl+R / Cmd+R.
Structured Output Contract Sync
The JSON schema for structured AI responses is shared between the backend and webview.
Run this when changing the structured output contract:
npm run structured-output:sync
Verify generated files are up to date:
npm run structured-output:check
Packaging
Install vsce:
npm install -g @vscode/vsce
Build and package:
npm run build
vsce package
This creates a .vsix file that can be installed through:
Extensions → Install from VSIX
Publishing
Marketplace packaging uses hosted image/content URLs.
VSCE_BASE_IMAGES_URL="https://your-cdn-url.com" npm run package:marketplace
Publish:
VSCE_BASE_IMAGES_URL="https://your-cdn-url.com" npm run publish:marketplace
Logging
The extension includes structured logging with correlation IDs, feature flow tracking, and performance monitoring.
Enable File Logging
Add this to settings.json:
{
"opencode.logging.enableFile": true,
"opencode.logging.level": "info"
}
Analyze Logs
npm run analyze-logs:summary
npm run analyze-logs:flows
npm run analyze-logs:errors
npm run analyze-logs:perf
Viewing Logs
Open:
Output → OpenCode
For full details, see:
LOGGING.md
Testing
Run all tests:
npm test
Run a specific test file:
node --test tests/plan-parser.test.mjs
The test suite covers:
- Plan parsing
- Structured output validation
- Quota logic
- Subagent tracking
- Message streaming
- Session CRUD
- UI contracts
- MCP/LSP panels
- Model dropdown behavior
Regression Guardrails
Install repo-managed git hooks:
npm run hooks:install
Run the local pre-push guard manually:
npm run guard:prepush
Run impacted tests only:
npm run test:impacted
The guard checks:
- Structured output contract
- Extension compile
- Type checking
- Linting
- Webview build when needed
- Impacted regression tests
Core Feature Protection
The following features should not be silently removed or broken:
- Token usage sticky header
- View Implementation Plan button
- Stop Request button
- React webview contract
- Chat script and stylesheet loading
- Plan viewer workflow
- Session persistence
- Subagent tracking
- Quota monitor
Contributing
- Fork the repository.
- Create a feature branch.
- Follow the rules in
AGENTS.md.
- Run the required checks.
- Open a pull request with a clear summary.
Before opening a PR, run:
npm run structured-output:check
npm test
License
MIT
Credits
Built on top of OpenCode by Anomaly.
