Varro: OpenCode Workbench

Varro runs OpenCode inside VS Code. It adds project-aware chat, parallel sessions, plan and change review, model and permission controls, commit-message generation, and usage reports.

OpenCode remains responsible for agents, providers, models, commands, skills, MCP servers, and their configuration. Varro reads that configuration and provides a VS Code interface for it.

Quick start

1. Install Varro from the VS Code Marketplace.
2. Install the OpenCode CLI with npm install -g opencode-ai.
3. Run opencode auth login, or use /connect in Varro, if no provider is configured.
4. Open a folder in VS Code and select Varro from the Activity Bar.
5. Start a session. Varro starts or connects to OpenCode when needed.

On native Windows, install OpenCode from a Windows terminal because Varro runs it on the local Windows extension host. In a VS Code WSL window, install OpenCode inside that WSL distribution instead. Varro and OpenCode then run on the Linux extension host. OpenCode recommends WSL for the best Windows experience, although native Windows is supported. Native OpenCode data, including auth.json, logs, and sessions, is under %USERPROFILE%\.local\share\opencode.

Varro supports VS Code and VSCodium. Support for other VS Code forks is limited; see VS Code fork compatibility.

Why Varro

• Choose among the providers and models supported by OpenCode instead of tying the editor to one model vendor.
• Reuse OpenCode agents, commands, skills, MCP servers, and project instructions. The same configuration remains available in Varro, the OpenCode TUI, and other OpenCode clients.
• Run multiple OpenCode sessions in the sidebar or editor tabs. Search, resume, fork, pin, share, export, archive, and recycle sessions.
• Follow streaming responses, reasoning, tool calls, questions, permissions, todos, plans, and file changes in one transcript. Routine completed work is grouped into expandable summaries.
• Include the active file and selection automatically. Attach files, folders, diagnostics, terminal output, images, PDFs, and references to other sessions.
• Queue follow-up prompts, steer an active run, or stop it and send a replacement.
• Set permissions per session to manual approval, automatic edit approval, rule or model-based approval, or full access.
• Select agents, providers, models, reasoning variants, and per-session MCP connections. Pin or hide models and inspect their known capabilities.
• Review changed files and optional inline diffs. Open completed plans or continue them in implementation sessions.
• Track context use, token counts, reported cost, and supported provider quotas. Generate cross-project usage reports with /stats.
• Generate a commit message from staged changes, or from unstaged changes when the index is empty. Varro fills the Source Control input but does not stage or commit files.
• Use VS Code light, dark, and high-contrast themes. Chats work in the sidebar, a maximized sidebar, or side-by-side editor tabs.

OpenCode feature coverage

Workbench means Varro provides dedicated UI. Integrated means OpenCode performs the operation and Varro exposes it. Handoff opens the relevant OpenCode or VS Code interface.

Sessions

Varro filters sessions to the current workspace and groups them into Recent, Archive, and Recycle Bin. Filters identify Running, Needs attention, Failed, Plan ready, and Completed sessions. Rows can show queued prompts, changed files, added and removed lines, token use, duration, and current state.

OpenCode search covers loaded and older root sessions. Open any session in the sidebar, an editor tab, or the OpenCode TUI. Root sessions can be pinned, renamed, shared, or recycled. Child sessions remain linked to their parent. On wide layouts, the session list can remain beside the active chat.

When Varro is hidden, VS Code notifications report plans, failures, permission requests, and questions from root sessions. The status bar links to sessions that need attention, then to completed background work.

Chat and context

Live document context includes the active file and selection by default. A chip in the composer shows this context and can disable it for the session. Use Varro: Add to Context or Cmd+Shift+K / Ctrl+Shift+K to add files, folders, line ranges, or terminal output. You can also drag files and folders into the composer or paste images.

Type @ to find workspace files and agents. Type & to reference a recent root session. The composer also shows active language servers, supports prompt history and undo or redo for attachments, and restores unsent text plus explicit file or folder attachments after a reload.

During a run, queue a follow-up, steer the current work, or stop it and send a replacement. Queued prompts can be reordered, paused, resumed, edited, retried, removed, or sent immediately as steering.

Commands stream their output. Failures, questions, approvals, file edits, and the final response remain visible. Completed routine work and thinking are grouped under summaries such as Explored and Worked. You can expand summaries, open long tool input or output in an editor, show thinking, or enable inline file previews.

Other chat workflows include rendered Mermaid previews, transcript turn navigation, changed-file links, Source Control handoff, reconnecting sessions after reload, and commands such as /review, /compact, /export, /stats, /skills, /diagnostics, /fork, and /ralph. Ralph runs support iteration, verification, repair, pause, and resume, and use Full access.

Permissions

Permission requests provide Reject, Once, and Always actions. Each session has one of three modes:

• Default follows OpenCode and agent permission rules.
• Auto applies local rules and, when needed, a configured model. Requests it cannot decide remain available for manual approval.
• Full access allows the session to act without confirmation.

Child sessions inherit the nearest selected mode in their session tree. Manual child requests appear in the parent conversation while remaining owned by the child session.

Varro initially selects Auto unless varro.chat.defaultPermissionMode or a saved project/global selection says otherwise. Default does not mean that every action requires approval. Without custom rules, OpenCode allows most permissions, asks for doom_loop and external_directory, and blocks reading .env files and variants while allowing .env.example. See OpenCode permissions to configure global or per-agent allow, ask, and deny rules, including rules matched by tool, command, path, subagent, URL, and external directory.

See the Varro permissions guide for mode behavior, manual approvals, and automatic review details.

Models, providers, and MCP

The model picker reads providers and models from OpenCode. It displays known tool, reasoning, image, PDF, and context-window capabilities. You can pin or hide models and set local display names without changing OpenCode IDs.

The Models view connects supported API-key and OAuth credentials through OpenCode. It also provides reauthentication when a provider reports an expired or revoked credential. Terminal-based OpenCode setup remains available.

A tool-capable text-only model can delegate image analysis to an OpenCode sub-agent named vision. Assign that agent an image-capable model and include an exact @vision mention in the prompt. See Add vision to a text-only model.

For read-only investigation, define a primary agent named ask with explicit read and search permissions. See Configure primary agents.

MCP servers come from OpenCode configuration and can be connected or disconnected per session.

Usage and limits

The composer shows context-window fill, and session rows show token use. The context popup separates input, output, reasoning, cache reads, cache writes, and sub-agent tokens. It also shows session cost when OpenCode reports it.

Run /stats or Varro: Usage Stats for a Markdown report from retained OpenCode history across all projects. It covers token use and total assistant duration for today, 7 days, and 30 days, grouped by provider and model. /stats all adds all retained history.

Varro shows quota windows and reset times when OpenCode metadata or a supported provider endpoint supplies them. Direct limit checks support OpenAI/Codex, GitHub Copilot, OpenRouter, xAI, Ollama Cloud, Z.ai, Kimi for Coding, and OpenCode Go. After a usage-limit error, you can stop retries or switch providers.

Commit messages

Select the wand in the Source Control toolbar or run Varro: Generate Commit Message. Varro uses staged changes if present; otherwise, it uses the unstaged working tree. It follows recent commit style when possible and writes the result to the selected repository's commit input for review.

Varro never mixes staged and unstaged changes, stages files, or commits automatically. It asks before replacing an existing draft, detects source changes during generation, and omits its temporary helper session from chat history. On native Windows, untracked file paths are included but their contents are omitted because Varro cannot guarantee an atomic no-follow read; tracked unstaged diffs are still included.

Server and updates

Varro connects to http://127.0.0.1:4096 by default. Set varro.server.port to another port from 1 through 65535. For manual server management, disable the deprecated debug setting varro.server.autoStart and run opencode serve --port 4096.

The status bar shows the active OpenCode version and available updates. On macOS and Linux, varro.server.autoUpdate installs the latest OpenCode CLI update. Native Windows does not replace the CLI in the background. It shows an update prompt, waits for active work to finish, and stops a Varro-managed server before opening the update command so Windows releases its lock on opencode.exe. Stop a separately managed server yourself before updating.

Varro reloads global OpenCode configuration when OpenCode is idle. Changes to project configuration may require Varro: Restart Server. This command waits for active work and only restarts a server managed by Varro. Restart a manually launched server in its terminal.

Requirements

• VS Code or VSCodium 1.120 or newer
• Node.js 22.22.2+ on Node 22, or Node 24.15.0+
• OpenCode CLI 1.16.0 or newer on PATH, or configured through varro.server.command
• A trusted, non-virtual workspace. Remote workspaces run Varro and OpenCode on the remote extension host

Documentation

• Usage guide
• Permissions guide
• Configure primary agents
• VS Code fork compatibility
• Development guide
• Architecture overview
• Issues and feature requests

License

MIT