# OpenCode Sidebar Chat: Agent GUI
You already have `opencode`. What a terminal cannot show you is the work.
This extension puts the agent in your VS Code sidebar: the conversation, every tool call as it lands, the diff before it is applied, and the service's health on the days it misbehaves. When a split terminal is the wrong shape for the job, open the same session in an editor tab instead.
> Independent project. Not affiliated with, or maintained by, the OpenCode team ([Anomaly](https://github.com/anomalyco/opencode)). Built on the released OpenCode 2 API (`@opencode/client` 2.x).
## Why this one
The official `opencode` extension does one job and does it well: it opens the CLI in a split terminal, shares your current selection with it, and stays out of the way. A terminal is what a lot of people want, which is why that extension has over a million installs.
This is the other job. Same agent, same config, same providers, but the session is drawn on screen: each tool call lands where you can read it, the diff appears before it is written, and an approval waits for your answer.
If the terminal is where you want to work, keep using it. Nothing here replaces the CLI, which is still running underneath.
## What it feels like
When the agent runs a shell command you watch the output arrive instead of a spinner. A tool call opens into its input and its result. Reasoning streams in full, or stays collapsed to one line, whichever you set. The context meter fills as the window does and warns before the turn that would have overflowed it, and the cache share beside it says how much of that context the provider was able to reuse.
Approvals are the part people notice first. A card appears in the conversation, says what will run, and spells out exactly what "always allow" writes into your project before you agree to it.
There is one detail you only notice if you have used a sidebar chat that gets it wrong: after you send, the transcript stays on the line you were reading. A long answer can arrive underneath you without moving your place, and the Jump to latest pill is there for when you do want the tail.
The rest is the work around the work. Sessions you can search, fork, archive and export, read as a flat list or grouped by project or by time. A real PTY terminal with tabs that survives the window. Worktrees, project instructions, per-session environment, MCP servers, providers and plugins in drawers. Scheduled prompts, published artifacts, `/web` search that sends real sources with the prompt, and `/btw` side questions that never enter the transcript.
Six palettes and two densities, and a conversation width you pick, so a full-screen tab fills the window instead of leaving a narrow column down the middle of it.
## Two honest limits
It is a client, not a fork. If the daemon does not serve a feature, this cannot invent it, and version-sensitive panels say so plainly when the daemon is too old.
And it needs the CLI. **OpenCode: Install CLI** handles that, including a Windows machine with no Node.js, but nothing here works without `opencode` underneath.
## Quick start
1. Get the CLI: **OpenCode: Install CLI** from the command palette, or install it yourself (see **Requirements**).
2. Open a workspace folder and click the OpenCode icon in the activity bar.
3. If no service is running, click **Start OpenCode** in the sidebar, or turn on `server.autoStart`.
4. Type a prompt. `/` is commands and skills, `@` attaches a file, and the `⋯` menu holds the rest.
## Requirements
- **VS Code 1.96 or newer.**
- **The OpenCode CLI**, installed locally as `opencode`. The extension can install it and keep it current for you.
Get it from the command palette with **OpenCode: Install CLI**, or follow the [OpenCode 2 install guide](https://opencode.ai/v2/docs). Use the 2.x install: `https://opencode.ai/docs` is the older 1.x documentation and installs a different package (`opencode-ai`), which this extension cannot drive.
Keeping the CLI current
The extension checks at most once every four hours whether that CLI is current. When a newer release exists, the header shows a **CLI 2.0.x → 2.0.y** pill with an update action; there is no separate update bar and no skip, so an available update stays visible until you take it. Run **OpenCode: Check CLI Updates** to check on demand, or turn the automatic check off with `cli.checkForUpdates`.
Set `cli.autoUpdate` if you would rather not be asked: the extension then updates the CLI as soon as it finds a newer release. This follows the CLI's own `update` setting in your opencode config as well, so `"update": "auto"` does the same thing and `"update": "disable"` stops the extension checking on its own (**OpenCode: Check CLI Updates** still works when you ask). Either way the update is the CLI's own (`opencode upgrade`), which picks both the package manager that actually owns your install (npm, pnpm, bun, yarn, vp, Homebrew, or the standalone installer) and the release itself, so the version in the pill is what we last saw published rather than a pin, and it comes from the same release channel the CLI reads. If the CLI cannot reach that channel at all, the extension fetches the same release itself: through npm for an npm-installed CLI, or from opencode.ai for the standalone install. Updating the CLI restarts the background service for you when no sessions are running, so the new build is actually in use; if sessions are live it leaves the service alone and offers a **Restart service** button instead. On Windows the service is stopped for the swap while the running build is locked, and started again afterwards.
If you still have the pre-release `opencode2` binary from the OpenCode 2 beta, it keeps working as a fallback and the update prompt will offer to move you to the released CLI.
Windows without Node.js
A Windows machine with no Node.js is covered: the extension downloads the standalone build from opencode.ai using the `curl` and `tar` that Windows already ships.
Flatpak
Install the CLI on the host, not in the sandbox. The extension reads the host's service registration through `flatpak-spawn --host`, so it normally needs no extra permission. If you would rather expose that directory to other tools as well, name your own app: `flatpak override --user --filesystem=~/.local/state com.vscodium.codium` (for VS Code itself, `com.visualstudio.code`; the id to use is the one in `FLATPAK_ID`).
Newer or older service versions
The extension builds against `@opencode/client` 2.x. Newer or older service versions usually work. If something breaks after a CLI update, check the `OpenCode` output channel and run **OpenCode: Restart Background Service**.
## Commands
| Command | Description |
| -------------------------------------- | -------------------------------------------------------------------- |
| `OpenCode: Focus Sidebar` | Focus the OpenCode view |
| `OpenCode: Toggle Sidebar` | Open or close the sidebar |
| `OpenCode: Open in Editor Tab` | Move the chat into a full editor tab |
| `OpenCode: New Session` | Create and select a fresh session |
| `OpenCode: Refresh` | Reconnect and resync |
| `OpenCode: Restart Background Service` | Force a new service connection |
| `OpenCode: Show Extension Server URL` | Show the companion server's address for this window |
| `OpenCode: Restart Extension Server` | Restart the in-process companion server |
| `OpenCode: Open Terminal` | Launch the CLI in a terminal |
| `OpenCode: Install CLI` | Install or update the CLI (npm, curl, brew, or the standalone build) |
| `OpenCode: Check CLI Updates` | Compare the installed CLI with the released one |
| `OpenCode: Start Companion Server` | Open the Companion panel: server, URL and pairing QR |
| `OpenCode: Stop Companion Server` | Stop the pairing server |
| `OpenCode: Remove Start-at-Login Item` | Delete the login item and its startup files |
| `OpenCode: Ask About Selection` | Send the selected code as a question |
| `OpenCode: Attach Selection` | Attach the selected lines to the composer |
| `OpenCode: Open Voice Session` | Open the voice page in your browser |
## Settings (`opencode2.*`)
The setting prefix is still `opencode2` because that is the extension's ID; renaming it would move every existing user's configuration. Common settings:
| Setting | Default | Description |
| ---------------------------- | --------------------- | ------------------------------------------------------------- |
| `server.autoStart` | `false` | Start a background service automatically when none is found |
| `server.mode` | `own` | `own` starts a hidden service, `discover` finds a running one |
| `cli.checkForUpdates` | `true` | Offer to update the CLI when a newer release exists |
| `cli.autoUpdate` | `false` | Install newer CLI releases without asking |
| `models.default` | `opencode/big-pickle` | Default model for new sessions as `providerID/modelID` |
| `permissions.mode` | `askFirst` | Ask first or auto allow |
| `ui.theme` | `dark` | Sidebar theme preset |
| `ui.density` | `compact` | `compact` or `comfortable` |
| `ui.chatWidth` | `wide` | `comfortable` (~780px), `wide` (~1100px) or `full` |
| `sessions.autoTitle` | `false` | Generate a title after the first completed turn |
| `agent.autoCompactThreshold` | `0` | Send a manual compact at this context percent, `0` disables |
| `server.listenEnabled` | `false` | Host the companion server for remote clients |
| `server.listenGlobal` | `false` | Keep the companion running (tray icon) after VS Code closes |
| `server.startAtLogin` | `false` | Start the companion automatically when you log in |
## The `⋯` menu
The header menu is where the panels live, so nothing appears until you ask for it:
- **session**: copy the transcript, fork, open the timeline, compact now, retry, undo or redo a turn, discard a staged revert, export or import
- **review**: the inbox of queued follow-ups, working changes, review against a branch or a commit, the plan checklist, scheduled prompts, artifacts
- **workspace**: instructions, worktrees, session environment, **terminal**, **shell**
- **configure**: models, providers, MCP servers, saved permissions, the config file, VS Code settings
- **appearance**: themes, reasoning display and chat width
After a divider come the service and adoption rows: restart the background service, reconnect only, usage and statistics, the companion panel and the tip jar.
## Companion server (optional)
Off by default, and it stays off unless you turn it on in the **Mobile & Companion** panel. It serves the same OpenCode to remote clients (the Android app, a browser, Tailscale) behind one stable address with its own username and password, so you can chat, review sessions and use a terminal from your phone. The panel sets the bind address, port and auth, and lists every address your phone can reach with a Copy button.
The Android client is **OC2 Companion**, a paid app: the phone features are included and the landscape tablet workspace is a one-time in-app purchase. It is in closed testing today, and the **Mobile & Companion** panel carries the link to join the test, or to get it once it is on Google Play. It is an independent project, not affiliated with or endorsed by Anomaly, the makers of OpenCode.
`server.listenGlobal` keeps it running (with a tray icon) after VS Code closes, and `server.startAtLogin` brings it up when you log in. Both are off by default.
## Voice sessions (optional)
Voice is off by default. Turn on `opencode2.voice.enabled` and a microphone button appears in the sidebar header (**OpenCode: Open Voice Session** does the same thing). It opens a voice page in your browser, where you press **Start voice session** and talk; the model answers with speech.
Why a browser page: a VS Code panel cannot reach a microphone. Webviews are sandboxed without microphone permission, so a voice session runs in a real browser tab, served by the companion server, and the audio goes straight from that tab to the provider.
What you say becomes work, not just text. With **Send requests to the agent** on (the default), each finished request goes into the session you have open as a **Voice** message, and the agent starts on it, exactly as if you had typed it, with the same model, permissions and history. It does not touch the composer: a draft you are typing stays where it is, and a spoken request never picks it up. Turn that switch off and the call becomes dictation: the transcript is staged in the composer as an editable draft and nothing is sent for you. Messages sent this way are marked **Voice** in the conversation, so you can still tell them apart from typed prompts afterwards. If a request needs your approval, the ask appears in VS Code while the call keeps running.
What it needs:
- **The companion server running**, because it serves the page.
- **An API key stored on the server** for the provider whose model you use. A ChatGPT sign-in is not enough; voice needs `OPENAI_API_KEY` or a stored OpenAI key (or `XAI_API_KEY` for `grok-voice`).
- **A voice-capable model**: `gpt-live`, `gpt-realtime` (OpenAI, over WebRTC) or `grok-voice` (xAI, over WebSocket). Leave `opencode2.voice.model` empty to use the first one the server offers.
`opencode2.voice.session` is an advanced setting: a JSON object sent with the session request. Providers only transcribe your own speech when asked, so the assistant's words arrive on every model while your side needs this. For OpenAI that is:
```json
{ "audio": { "input": { "transcription": { "model": "gpt-4o-transcribe" } } } }
```
A wrong shape makes the provider reject the session, and its message is what the page shows.
## Workspaces
New sessions use your open folder. The header shows the folder and git branch. Change session scope between this folder and all projects in the sessions drawer, and read the list three ways: Recent for a plain newest-first list, Projects for one collapsible drawer per project folder with the open folder pinned first, or Activity for Today, Yesterday, the last 7 and 30 days, and Older. Archiving a session takes it out of the list on every client, including the phone companion, and the archived scope restores it; that needs OpenCode 2.1 or newer.
## Privacy
The extension is a client. Your prompts, code and API keys go to the OpenCode service on your machine, which owns provider auth; the extension does not keep a copy of your keys and does not send anything to a server of ours. The two optional features that reach outside your machine say so: the companion server binds to an address you choose and requires its own login, and a voice session sends audio straight from the browser tab to the provider.
## Troubleshooting
OpenCode ships its own diagnostics for the shared background service. From a terminal:
```sh
opencode service status # is the daemon up, and on which URL
opencode api get /api/status # the API's own status answer, using service discovery and auth
opencode service restart # restart the daemon
opencode --version # the CLI build you are running
```
Logs are at `~/.local/share/opencode/log/opencode.log`. Every line carries a `run` id, and `role=server` marks session, provider, permission and tool activity, which makes `grep 'role=server'` the fastest way to see what the service did.
Inside VS Code, the extension writes to its own `OpenCode` output channel, and **OpenCode: Restart Background Service** (also in the header `⋯` menu) reconnects and starts a fresh service. When reporting a problem, include `opencode --version` and `opencode service status`.
## License
Free to use, including for commercial purposes. The **source is not available**. It is proprietary: copying, modification, redistribution, and reverse-engineering are reserved. The full terms ship in the `LICENSE` file bundled with the extension.