Varro：在 VS Code 中运行 OpenCode 的扩展

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.

Supports OpenCode v2 and v1. Varro automatically detects the connected API and uses the same workbench for either version. OpenCode v2 is recommended for new installations.

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 OpenCode v2 with npm install -g @opencode/cli on macOS, Linux, or WSL. For native Windows, download the standalone CLI from that page.
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.

Already using v1? You can keep it, or install it with npm install -g opencode-ai. Set varro.server.command to your v1 executable to select it explicitly. With this setting empty, Varro searches for opencode2 first, then opencode. Current v1 and v2 packages both install opencode, so the command name alone does not identify the version. Run opencode --version to check. See choosing and updating OpenCode before switching versions.

After switching from v1 to v2, you may need to run Varro: Restart Server from the Command Palette. Installing v2 does not replace an already running v1 server. If restart fails or Varro still shows v1, stop the old OpenCode process explicitly, especially on Windows, then restart with the v2 executable. Let active work finish first. See restart recovery steps and confirm the connected version in Varro's status bar.

Install OpenCode on the host where Varro runs. A native Windows VS Code window needs the Windows CLI; add it to PATH or set varro.server.command to its executable path. A VS Code WSL window needs OpenCode installed inside that WSL distribution. Native OpenCode data is under %USERPROFILE%\.local\share\opencode; WSL uses the Linux data directory.

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.

Coverage depends on the connected version. The supported v2 API has no session sharing or OpenCode LSP service. Varro disables sharing on v2; VS Code Problems can still be attached as context. V2 session annotations are stored locally by Varro. See version differences and history import.

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.

Indicators at the top of the chat summarize activity in other sessions: a numbered spinner means running, blue means waiting for input or permission, red means failed, yellow means a plan is ready, and green means completed. Select an indicator to open the matching session or filter. Colors may vary with the active VS Code theme. See the usage guide for details.

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.

Desktop notifications

Enable OS banners with varro.notifications.native and select sound events with the varro.notifications.sound checkboxes. Both are off by default. Alerts cover permission requests, questions, completed replies, and plans ready for review. On macOS, alerts stay quiet while any window from the originating VS Code instance is visible, even when unfocused. Minimized or fully covered windows allow alerts. Other platforms use window focus.

Notifications show Project: <name>, the chat title, and event details. Clicking opens the project's VS Code window. Bursts are grouped; automatically handled requests and old completions stay quiet.

Requires a local desktop host; remote SSH, WSL, and containers are unsupported. macOS 11+ uses a bundled Varro-owned helper; allow Varro in System Settings > Notifications. Linux needs notify-send for banners and paplay, aplay, or canberra-gtk-play for sound. OS permissions and Focus/Do Not Disturb settings apply.

Experimental macOS menu-bar app

The optional native companion app lists active sessions, events needing attention, and unread completions across local VS Code windows. Its badge includes unread completions, which disappear when marked read in VS Code. Clicking a row opens its project window without switching chats. On macOS 13+, build and install it with make build and make install from native/macos-tray/. The extension works as usual without it.

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.

With OpenCode V2, /pause interrupts the current session run and pauses its queued messages in the current view. A Paused divider marks the transcript. Hover over it or focus its Resume button to continue; sending a new message or playing a queued message also continues the session. The divider then reads Paused and resumed. Pause markers survive reopening the session. This preserves the conversation but does not suspend an in-flight model response or tool operation for exact resumption.

Paused time is excluded from worked-duration summaries and usage statistics. Resuming starts a new work period, so returning hours later does not inflate the previous run's duration.

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 follows the connected OpenCode version's global and agent rules. V2 uses ordered permissions rules with action, resource, and effect; supported v1-format rules remain accepted. See v2 permissions or v1 permissions for syntax and defaults.

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.

For inline prompt suggestions, right-click an eligible fast model and choose Use for prompt completion, or set varro.chat.promptCompletionModel to provider/model. This requires OpenCode V2 and an API-key connection using a supported direct API: OpenAI Responses, Meta Responses or Chat Completions, OpenRouter Chat Completions, OpenAI-compatible Chat Completions, or Anthropic Messages. Completion actions have their own menu group after the agent assignments and appear only for eligible connections. An already assigned unsupported model still has a removal action. A manually entered unsupported setting is rejected too. Varro never creates utility chats for prompt completion.

Native Z.AI and GLM Coding Plan Chat Completions packages are supported, including the separate Coding Plan endpoint. GLM uses its own thinking controls and max_tokens; GLM-5.3 keeps mandatory thinking at the lowest advertised effort, or low when variants are missing. Native Baseten, Cerebras, DeepInfra, DeepSeek, DigitalOcean, Fireworks, Groq, Together AI, xAI, explicit OpenAI Chat/Responses, compatible Responses, and Anthropic-compatible packages are also supported. Completion uses its own HTTP request regardless of the chat's HTTP/WebSocket preference. OAuth-only connections, Azure, Vertex, Bedrock, Gemini, and unrecognized package protocols remain excluded from direct prompt completion.

Failed suggestions use the model-selection warning icon beside the model and reasoning controls, with the error in a hover or keyboard-focus tooltip. If both warnings apply, their messages share one tooltip. The completion warning stays visible through typing and retries until a current request succeeds, including a successful empty response. Sending or queueing the prompt, clearing the input, changing chats, changing the completion model, or disabling completion resets it. The text caret uses the accent color while a completion request is in flight and returns to its normal color when the request finishes or is cancelled. There is no spinner. Cancelled requests and intentionally empty suggestions do not create a warning. Right-click a model in the provider list and choose Test prompt completion to make one direct API call using a fixed sample draft. A VS Code notification reports success or failure and elapsed time. The test may consume provider usage; it never uses your conversation history or changes the assigned completion model.

This is off by default. After a 600 ms typing pause, Varro sends your draft, only the last ten user prompts from the same chat, and the latest available agent reply directly to that model using its lowest advertised reasoning variant, or disables thinking for Anthropic Messages. The completion model is instructed to continue the human user's prompt to the agent, not answer it or claim to perform work. Repeated user prompts are preserved; child chats and other sessions are excluded. Only ordinary text from the latest agent reply is included, not reasoning, tool output, synthetic text, or compaction summaries. Each historical user prompt is bounded to 1,000 characters, and the latest reply retains at most its final 6,000 characters so concluding questions remain available. New chats send no conversation context. Credentials stay in the extension host. Typing again cancels the pending request. Tab accepts the muted suggestion and suppresses further suggestions until the text changes. Drafts ending with a period, including trailing whitespace, do not request suggestions. Escape dismisses a suggestion, and Enter sends only typed or accepted text. Clear the setting or choose Don't use for prompt completion to turn it off, even if the assigned provider is no longer supported.

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, reset times, and available OpenAI/Codex or Z.ai usage-limit resets when supported provider endpoints supply 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.

With the opencode-claude plugin on OpenCode V2, Varro also reads limits for varro-claude, displayed as Claude Code (CLI). It uses the authenticated loopback endpoint advertised in the provider settings. The plugin runs Claude Code's /usage command and returns account usage windows, remaining percentages, and known reset times. Varro does not read Claude credentials for this adapter. Limits are unavailable in attach-only mode, where the plugin endpoint may be on another host.

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 selects and remembers a local port by default with varro.server.port: "auto". Existing verified servers survive extension updates and reloads without a migration restart. New managed servers require credentials. Set an integer port from 1 through 65535 for a fixed endpoint; explicit ports never silently fall back. For manual server management, set the port explicitly, disable the deprecated debug setting varro.server.autoStart, and run opencode serve --port 4096.

Attachment to a different OS user's listener, or one whose owner cannot be verified, requires confirmation before sessions or events are loaded, even with supplied credentials. This prevents accidental attachment; it does not secure an unauthenticated server against other clients. See ownership and migration.

The status bar shows the active OpenCode version and available updates. varro.server.autoUpdate installs updates within the installed CLI family: @opencode/cli for v2 on Windows, macOS, and Linux, or opencode-ai for v1 on macOS and Linux. Updating v1 does not migrate it to v2. Native Windows v2 runs the resolved CLI's update <latest-version> command in the background and verifies the installed version; server restarts still wait for active work to finish and require Varro ownership. Native Windows v1 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 a prompted Windows update.

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 v2 CLI 2.0.5+ recommended, or v1 CLI 1.16.0+, on PATH or configured through varro.server.command. Tested with v2 2.0.26 and v1 1.18.35
• A trusted, non-virtual workspace. Remote workspaces run Varro and OpenCode on the remote extension host

Documentation

• Usage guide
• Docker Sandboxes with Remote SSH: suggested step-by-step setup for running Varro and OpenCode inside a sandbox
• Docker and remote servers: advanced setup with reduced functionality, not recommended for general use
• Permissions guide
• Configure primary agents
• VS Code fork compatibility
• Development guide
• Architecture overview
• Issues and feature requests

License

MIT