How to Use OpenCode in VS Code: 7 Setup and Workflow Checks

The VS Code integration does not replace the OpenCode CLI. It gives the CLI editor context, shortcuts, and a predictable split-terminal launch point. Install OpenCode first, open the repository you actually want to work on, and run opencode --version in VS Code's integrated terminal. If that command is not found there, the extension cannot repair the missing executable. Fix the shell PATH before testing editor features.

Use a real project folder rather than an empty editor window. OpenCode makes better decisions when it can see the repository boundary, Git history, configuration, and the files referenced by your selection. Before the first session, review ignored files and remove secrets from ordinary source files. An IDE integration makes context sharing convenient, so it also makes accidental context sharing easier if the project is poorly organized.

Confirm that your model provider already works in a normal OpenCode session. A provider authentication failure, unavailable model, proxy error, or rate limit can occur after the IDE launches correctly. Separating CLI, provider, and extension checks prevents you from reinstalling the extension when the real failure is upstream. The homepage deployment guide covers the broader provider setup; this page keeps its scope on VS Code integration.

First, open VS Code and load the repository folder. Second, open Terminal > New Terminal so the shell starts inside that workspace. Third, run opencode. According to the official IDE documentation checked on July 29, 2026, OpenCode detects VS Code and installs its extension automatically. Fourth, let the CLI finish starting and confirm that the terminal session can read the current project. Fifth, press Ctrl+Esc on Windows or Linux, or Cmd+Esc on macOS, to verify that the extension can open or focus the split terminal view.

Automatic installation is the best default because it proves that the CLI, editor, and extension belong to the same environment. If you prefer a manual path, search for OpenCode in the VS Code Extension Marketplace and choose Install. Manual installation can restore the UI integration, but it still requires a working opencode command. Do not treat an installed extension badge as proof that the executable, provider, or workspace permissions are correct.

For a separate conversation, use Ctrl+Shift+Esc on Windows or Linux, or Cmd+Shift+Esc on macOS. This starts a new OpenCode terminal session even when another is already running. Use separate sessions deliberately: one for a focused implementation task and another for investigation can be useful, but two agents editing the same files at once create avoidable conflicts. Keep each session's goal and file boundary explicit.

The main benefit of the extension is context awareness. Select the smallest block that explains the problem before asking a question. A function, error-handling branch, or configuration object is usually more useful than an entire large file. OpenCode can also use the active tab, but an explicit selection reduces ambiguity and helps you review exactly what was shared with the terminal session.

Use Alt+Ctrl+K on Windows or Linux, or Cmd+Option+K on macOS, when you want a durable file reference in the prompt. The official example uses a shape such as @File#L37-42. Line references are valuable for review questions and narrow refactors because the prompt documents the intended boundary. Recheck the line range after large edits, since inserted or deleted lines can make an old reference point at different code.

Context is not the same as permission. A selected block helps OpenCode understand your request, but file edits and shell commands still follow the configured OpenCode permission policy. Ask for an explanation first when you are unsure, inspect the proposed plan, then allow a narrow edit. The editor makes reviewing diffs easier; use that advantage instead of granting broad permissions only to save one confirmation.

Start each task with the repository state. Check Git status, describe the expected outcome, and identify files that must not change. Then select the relevant code or add file references before asking OpenCode to inspect the problem. For implementation work, request a short plan only when the change spans several modules; for a narrow fix, ask for the edit and its validation directly. The goal is a clean diff, not a long conversation.

Keep the integrated terminal visible while OpenCode runs commands. You should be able to see which working directory is active, which command was requested, and whether the result belongs to the same environment as VS Code. After an edit, review the Source Control diff, run the smallest relevant test or formatter, and then run the broader project check when risk justifies it. A green command without a reviewed diff is incomplete evidence.

Use new sessions for context resets, not as a substitute for closing finished work. If a session has accumulated unrelated instructions, start another with Ctrl+Shift+Esc or Cmd+Shift+Esc and restate the task boundary. Keep one owner per changing file when multiple sessions or teammates are involved. Commit only after the intended changes, generated output, and validation results are understandable from the diff.

VS Code may open different shells depending on your profile, remote environment, container, or operating system. Confirm the terminal profile before approving commands, especially when the workspace is attached through SSH, WSL, Dev Containers, or a network share. A command that is harmless in a local clone may affect a remote service when the integrated terminal points elsewhere. Put the environment name in your own task notes and verify the prompt path before destructive operations.

Do not select secrets, private keys, production configuration, customer records, or large unrelated files merely because sharing context is convenient. OpenCode sends relevant context to the configured model provider unless you are using a verified local-provider setup. Review provider retention and organizational policy separately. Use environment variables or secret managers, keep sensitive files ignored, and redact values from error examples before asking for help.

Permission rules should reflect the repository, not the editor. Allow read-only inspection broadly enough for useful analysis, require confirmation for commands with side effects, and keep deployment, database, payment, and authentication changes under explicit human review. The extension should shorten navigation between editor and terminal; it should not silently widen what an agent is allowed to do.

When automatic installation fails, first prove that opencode runs inside the VS Code integrated terminal. A command that works in an external PowerShell, Terminal, or shell window may be missing from VS Code because the editor was opened before PATH changed. Fully close and reopen VS Code after installing the CLI. Then compare the executable location in both shells and confirm that the workspace terminal uses the expected profile.

Next, confirm that the VS Code code command is installed. The official OpenCode troubleshooting guide lists code for VS Code, cursor for Cursor, windsurf for Windsurf, and codium for VSCodium. On macOS, open the Command Palette and run Shell Command: Install 'code' command in PATH. On Windows or Linux, confirm that code --version works in the same integrated terminal. Finally, verify that VS Code is allowed to install extensions and that organization policy has not blocked the marketplace.

If the extension is present but shortcuts do nothing, check VS Code Keyboard Shortcuts for conflicts before reinstalling. If the session opens but has no project context, verify the active workspace, selected text, and terminal working directory. If the session starts but the model fails, return to provider authentication, model availability, proxy, and rate-limit checks. Each layer has a different owner, so test one layer at a time.

Reinstalling is appropriate when the CLI works in the integrated terminal, the code command is available, provider requests succeed, and only the editor commands remain missing or corrupted. Remove the OpenCode extension from VS Code, close every editor window, reopen the repository, and run opencode in a fresh integrated terminal so automatic installation can rebuild the connection. Then test the quick-launch shortcut before restoring custom keybindings.

If your editor has no supported extension workflow but does support a terminal, you can still run OpenCode there. You lose some automatic selection and shortcut behavior, but the terminal session remains usable. For /editor or /export behavior from the TUI, the official docs recommend setting EDITOR to code --wait for VS Code. Keep this separate from the extension setup: EDITOR controls which external editor command OpenCode invokes, while the extension controls IDE context and shortcuts.

A successful setup ends with evidence: the CLI runs in the project folder, the extension opens or focuses the session, selected code arrives as intended, a small edit produces a reviewable diff, and the relevant test passes. Record the VS Code, OpenCode, operating system, terminal profile, and provider used for that baseline. Those details make later regressions much faster to diagnose.