OpenCode, the open-source terminal AI coding agent maintained by Anomaly, passed 194,000 GitHub stars in early August 2026, up from roughly 172,000 stars in early June, according to a provider tracker published by MorphLLM. That growth rate puts it ahead of both Google’s Gemini CLI and OpenAI’s Codex CLI by star count, and it explains why “opencode install” and “opencode setup” have turned into some of the most searched terms in the AI coding assistant category this year. Unlike subscription tools such as GitHub Copilot, OpenCode itself costs nothing. You install it, connect an API key from whichever model provider you choose (or run a model locally for free), and pay only for the tokens you actually use.
This OpenCode tutorial walks through a full opencode install and setup from a blank terminal to a working project: picking an install method for your OS, connecting a provider, configuring opencode.json, wiring up MCP servers, creating custom OpenCode agents, adding the VS Code extension, and shipping a real feature with OpenCode’s help. Budget about 80 minutes if you follow every step, including the hands-on project near the end. Most of that time goes to waiting on downloads and typing prompts, not reading documentation.
Don't miss new tech stories on Google
Add Tech Insider once in the Google app and our stories appear in your news suggestions.
What Is OpenCode, and Why Are Developers Switching to It?
OpenCode is an open-source AI coding agent built for the terminal. It ships as three things at once: a text-based interface (TUI) you run inside any terminal emulator, a desktop app, and an IDE extension that drops into VS Code, Cursor, Windsurf, or VSCodium. The project is MIT licensed, and the OpenCode GitHub repository, anomalyco/opencode, had crossed 194,000 stars at the time of writing, making it the most-starred tool in the open-source AI coding assistant category.
What separates OpenCode from a typical coding assistant is how it handles models. Instead of shipping with one AI vendor baked in, it uses the AI SDK and Models.dev to support more than 75 LLM providers, including Anthropic, OpenAI, Google Vertex AI, Amazon Bedrock, Groq, DeepSeek, xAI, and any Ollama model running on your own machine. You are never locked into a single company’s pricing or a single model’s quirks. If you already use Claude Code or another terminal agent, the workflow will feel familiar: you type natural-language requests, OpenCode edits files and runs commands, and you review diffs before they land.
The tool itself doesn’t charge a subscription. Anomaly’s revenue comes from optional add-ons like OpenCode Zen, a curated set of pre-tested models billed by usage, and OpenCode Go, a low-cost subscription for popular open coding models. Neither is required. You can connect a provider you already pay for, such as an existing Anthropic or OpenAI account, or run models locally through Ollama at zero marginal cost. That flexibility is a big part of why OpenCode setup guides are trending across developer forums this year, and why it belongs on the shortlist any time someone asks about the best open-source AI coding assistant for a terminal-first workflow.
Why Go Open-Source for AI Coding in the First Place
Closed, subscription-based coding assistants bundle the interface, the model access, and the billing into one flat monthly fee. That’s convenient, but it also means you pay the same amount whether you write five prompts a day or fifty, and you’re stuck with whatever model mix the vendor decides to offer. Our GitHub Copilot setup guide covers that model in detail if you want the comparison.
Open-source terminal agents flip that arrangement. You bring your own API key and pay the model provider directly for usage, which industry analysis from 2026 pegs at near-premium coding performance for as little as $2 to $5 a month for moderate, personal-project use. Heavier professional use costs more, but you’re paying for tokens consumed, not a seat license. The other benefits stack on top of the cost savings: full visibility into what gets sent to the model, the option to run everything on local hardware for sensitive codebases, and no vendor able to change your pricing or feature set overnight. That’s the pitch behind an open source AI coding assistant like OpenCode, and it’s why terminal-first tools such as OpenCode, Cline, Aider, and Gemini CLI have all picked up momentum in the same stretch of 2026.
Prerequisites: What You Need Before You Start
OpenCode’s install footprint is small, but a few things need to be in place before you run the installer. Here’s the full list.
| Requirement | Detail | Required? |
|---|---|---|
| Terminal emulator | A modern one: WezTerm, Alacritty, Ghostty, or Kitty are officially recommended for full feature support | Yes |
| Operating system | macOS, Linux, or Windows (WSL recommended for the best experience on Windows) | Yes |
| Node.js 18 or higher | Only needed if you install via npm, Bun, pnpm, or Yarn | Conditional |
| API key for at least one provider | Anthropic, OpenAI, Google, OpenRouter, or another of the 75+ supported providers | Yes, unless local-only |
| Ollama (optional) | Only needed for the fully local, zero-cost setup covered in Step 9 | No |
| Git | For the working project walkthrough in Step 13 and for committing config files | Recommended |
If you don’t have Node.js installed and plan to use the npm install path, grab the current LTS release from the official Node.js download page first. Everyone else can skip straight to the install script in Step 2.
Step 1: Pick the Right Installation Method for Your OS
OpenCode ships install paths for every major package manager, so the first real decision is which one fits how you already manage software. There’s no wrong answer here. All paths install the same binary and get you to an identical TUI.
| Method | Platform | Best For |
|---|---|---|
| Install script (curl) | macOS, Linux | Fastest path, no package manager needed |
| npm / Bun / pnpm / Yarn | macOS, Linux, Windows | Developers who already have a Node.js toolchain |
| Homebrew (tap) | macOS, Linux | Homebrew users who want the most current release |
| Pacman / AUR | Arch Linux | Arch and Arch-based distros |
| Chocolatey / Scoop | Windows (native) | Windows users not using WSL |
| Mise | macOS, Linux, Windows | Teams already using Mise for toolchain versioning |
| Docker | Any platform with Docker | Sandboxed or CI environments |
If you’re on Windows, read this part carefully: OpenCode’s own documentation recommends using Windows Subsystem for Linux (WSL) for the best experience, citing better performance and full feature compatibility. Native Windows installs through Chocolatey, Scoop, or npm work, but you’ll hit more rough edges, particularly with terminal rendering. If you’ve never set up WSL, it’s a one-time, ten-minute detour that pays off for the rest of this guide.
Step 2: Install OpenCode
The fastest way to install OpenCode on macOS or Linux is the official install script. Open your terminal and run:
curl -fsSL https://opencode.ai/install | bashThis detects your platform automatically and installs the latest release. If you’d rather use a package manager, here are the alternatives, all pulled directly from OpenCode’s install documentation:
# Using Node.js (pick one)
npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai
# Using Homebrew on macOS and Linux (recommended tap, most up to date)
brew install anomalyco/tap/opencode
# Arch Linux
sudo pacman -S opencode # stable
paru -S opencode-bin # latest from AUR
# Docker
docker run -it --rm ghcr.io/anomalyco/opencodeOn Windows, if you’re not using WSL, install through Chocolatey, Scoop, or npm:
choco install opencode
scoop install opencode
npm install -g opencode-aiTeams that already standardize on Mise for toolchain management can add OpenCode the same way they add any other tool:
mise use -g github:anomalyco/opencodeWhichever method you pick, the install typically takes under a minute on a normal broadband connection. If you’d rather not run any installer at all, prebuilt binaries are also available from the project’s GitHub Releases page.
Step 3: Verify the Installation
Close and reopen your terminal window so your shell picks up the updated PATH, then confirm the binary is where your shell expects it:
# macOS / Linux
which opencode
# Windows (PowerShell)
where.exe opencodeThe real test is launching it. From any directory, run:
opencodeIf a terminal UI opens with a prompt box at the bottom, the install worked. Press ctrl+c twice, or use your leader key followed by q, to quit for now. You’ll come back to this same command in Step 5 once a provider is connected. If nothing happens or you get a “command not found” error, jump ahead to the troubleshooting section below, it’s a fast fix in almost every case.
Step 4: Connect Your First AI Provider
OpenCode doesn’t come with a model attached. You connect one (or several) yourself. Launch OpenCode and run the connect command:
/connectThis opens a picker listing every supported provider. If you’re new to picking a model provider, OpenCode’s own docs suggest starting with OpenCode Zen, a curated shortlist the OpenCode team has tested directly against their agent. Whichever option you choose, the flow is the same: selecting a provider opens opencode.ai/auth in your browser, where you sign in, add billing details, and copy an API key back into the terminal prompt that appears. Your credentials are then stored locally in ~/.local/share/opencode/auth.json, not on OpenCode’s servers.
Here’s a sample of the provider landscape you’re choosing from. This is a small slice of the 75-plus providers OpenCode supports through the AI SDK and Models.dev.
| Provider | Type | Notes |
|---|---|---|
| Anthropic | Cloud | Claude models, connected via API key or Claude subscription |
| OpenAI | Cloud | Supports ChatGPT Plus/Pro sign-in as an alternative to a raw API key |
| Google Vertex AI | Cloud | Gemini models through a Google Cloud project |
| Amazon Bedrock | Cloud | Auth via AWS access keys, named profile, or bearer token |
| OpenRouter | Cloud (aggregator) | Single key for access to many underlying model vendors |
| Groq / DeepSeek / xAI | Cloud | Lower-cost or specialized model options |
| Ollama | Local | Zero API cost, runs entirely on your own hardware, covered in Step 9 |
| OpenCode Zen / OpenCode Go | Cloud (curated) | Optional, pre-tested model bundles from the OpenCode team |
If you’re deciding between Anthropic and OpenAI as your primary provider, our breakdown of Claude Code versus Codex compares cost per task and model behavior in more depth, and most of that reasoning carries over to picking a default model inside OpenCode. Enterprise users on Amazon Bedrock can skip the browser flow entirely and authenticate through environment variables instead:
# Option 1: AWS access keys
AWS_ACCESS_KEY_ID=xxx AWS_SECRET_ACCESS_KEY=yyy opencode
# Option 2: named AWS profile
AWS_PROFILE=my-profile opencode
# Option 3: Bedrock bearer token
AWS_BEARER_TOKEN_BEDROCK=xxx opencodeYou can connect more than one provider. OpenCode lets you switch models mid-session with the /models command, which is useful if you want a cheaper model for routine edits and a stronger one for harder reasoning tasks.
Step 5: Initialize OpenCode Inside a Project
With a provider connected, navigate to the project you want OpenCode to work on:
cd /path/to/project
opencodeOnce the TUI is open, run the init command:
/initOpenCode scans your project, reading directory structure, dependency manifests, and existing code, then writes an AGENTS.md file to the project root. Think of it as an onboarding document for the AI: it typically captures the project layout, the languages and frameworks in use, and any conventions OpenCode inferred from the existing code, so future sessions don’t have to re-derive that context from scratch. Commit this file to Git. Every teammate who runs OpenCode against the same repo benefits from it, and it’s one of the biggest quality-of-life differences between a five-minute opencode install and a setup that actually saves you time every day.
Step 6: Learn the TUI and Core Slash Commands
Before diving into configuration, spend five minutes learning how to move around. OpenCode’s interface is entirely keyboard-driven, and a handful of slash commands cover most of what you’ll do day to day.
| Command | What It Does |
|---|---|
/connect | Add or switch an AI provider |
/init | Generate or refresh the project’s AGENTS.md file |
/models | Switch the active model |
/undo | Revert the last change OpenCode made, can be run repeatedly |
/redo | Reapply changes you just undid |
/share | Generate a shareable link to the current conversation |
/editor | Open the current context in your configured external editor |
@ | Fuzzy-search and reference a file from your project in a prompt |
Two habits are worth building early. First, use @ to reference files instead of describing them in prose. Typing @src/api/index.ts is faster and more precise than explaining a file path in a sentence. Second, if OpenCode makes a change you don’t like, reach for /undo before you start manually reverting files by hand. It reverts cleanly and re-shows your original prompt so you can tweak it and try again. Conversations are not shared by default, so /share is opt-in every time, which matters if you’re working on anything sensitive.
You can also drag and drop an image directly into the terminal window. OpenCode reads it and adds it to your prompt, which is a fast way to hand it a design mockup or a screenshot of a bug.
Step 7: Switch Between Build Mode and Plan Mode
OpenCode ships with two built-in primary agents, and understanding the difference will save you from unwanted file changes. Build is the default agent, with every tool enabled, including file writes and shell commands. Plan is a restricted agent designed for analysis: by default it sets file edits and bash commands to “ask,” so it can propose a plan without touching your codebase until you approve it.
Switch between them with the Tab key. An indicator in the lower right corner of the TUI shows which agent is active. The recommended workflow for anything bigger than a one-line fix looks like this: describe the feature while in Plan mode, let OpenCode propose an approach, give feedback and iterate on the plan (this is also where you’d drop in a reference screenshot), then hit Tab to switch to Build mode and tell it to go ahead. For small, well-understood changes, like fixing a typo or matching a pattern that already exists elsewhere in the file, skipping straight to Build mode is fine.
Beyond the two primary agents, OpenCode includes three built-in subagents that primary agents can call on automatically, or that you can invoke directly with an @ mention: General, a full-tool-access agent for multi-step research and parallel work, Explore, a fast read-only agent for scanning a codebase, and Scout, used for narrower lookups. You won’t need to think about these directly at first, but knowing they exist explains some of the behavior you’ll see once OpenCode starts breaking a big task into smaller pieces on its own.
Step 8: Configure opencode.json (Global vs. Project)
Once you’re comfortable with the basics, configuration is where OpenCode setup starts to feel like your own tool instead of a default install. OpenCode reads a JSON (or JSONC, JSON with comments) config file, and it supports two main locations that get merged together rather than one overriding the other entirely.
// ~/.config/opencode/opencode.json (global, user-wide)
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true,
"server": {
"port": 4096
}
}Place a global config at ~/.config/opencode/opencode.json for settings you want on every project: default model, autoupdate behavior, server preferences. Place a project-specific opencode.json in a repository’s root for settings that should only apply there, and check it into Git so the whole team shares it. When OpenCode starts, it looks for a config in the current directory and walks upward until it finds the nearest Git root.
The precedence order matters once you have more than one config source active. From lowest to highest priority: remote organizational config (fetched from a .well-known/opencode endpoint if your provider supports it), global config, a custom config pointed to by the OPENCODE_CONFIG environment variable, project config, then .opencode directories for agents and commands, and finally inline overrides via OPENCODE_CONFIG_CONTENT. Organization-managed settings, where applicable, sit above all of that. The practical takeaway: project settings win over global ones for the same key, but non-conflicting settings from every level are preserved, not thrown away.
You can also point OpenCode at a custom config file or directory using environment variables, which is handy for CI pipelines or shared team defaults that live outside the repo:
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"Step 9: Run OpenCode for Free with Local Models via Ollama
If you’d rather not send any code to a cloud provider, or you just want a zero-cost setup for side projects, OpenCode can run entirely against local models through Ollama. Install Ollama, pull a model, then point OpenCode at Ollama’s local endpoint in your config:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama2": {
"name": "Llama 2"
}
}
}
}
}Swap llama2 for whichever model you’ve pulled locally, such as a Qwen or DeepSeek coding model. If tool calls stop working with a local model, the most common fix is raising Ollama’s context window. Start around 16,000 to 32,000 tokens (the num_ctx setting) and adjust from there. Ollama also offers a hosted option called Ollama Cloud, which uses your normal /connect flow but requires pulling the model’s metadata locally first with a command like ollama pull gpt-oss:20b-cloud before it shows up in OpenCode’s model picker.
Local models won’t match a frontier cloud model on hard reasoning tasks, but for routine edits, boilerplate, and offline work, they close the gap more than most developers expect, and the cost is exactly zero per token.
Step 10: Connect MCP Servers to Extend OpenCode
The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources, things like a Jira board, a database, or a search API. OpenCode supports both local and remote MCP servers, and once you add one, its tools become available to the model automatically, right alongside OpenCode’s built-in tools.
Define MCP servers under the mcp key in your OpenCode config. Here’s a local server, using the reference “everything” MCP server as an example:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp_everything": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
"enabled": true
}
}
}And a remote server, authenticated with a bearer token in the headers:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-remote-mcp": {
"type": "remote",
"url": "https://my-mcp-server.com",
"enabled": true,
"headers": {
"Authorization": "Bearer MY_API_KEY"
}
}
}
}Once a server is configured, you reference it by name in a prompt, for example asking OpenCode to “use the mcp_everything tool” for a specific task. For remote servers that require OAuth, OpenCode handles the flow automatically: it detects a 401 response, initiates Dynamic Client Registration if the server supports it, and stores the resulting tokens securely for future sessions.
One caveat is worth flagging before your opencode mcp setup gets out of hand: every MCP server you enable adds its tool definitions to the model’s context window. A handful of lightweight servers is fine, but something like a full GitHub MCP server can add a large number of tokens on its own. Enable only the servers you’re actively using, and set enabled: false on the rest rather than deleting their config entirely, so you can flip them back on without re-typing everything.
Step 11: Create Custom Agents and Remap Keybinds
Beyond the built-in Build and Plan agents, OpenCode lets you define your own, each with its own system prompt, model choice, temperature, and permission set. A documentation agent, for instance, might get a restricted permission set and a prompt tuned specifically for writing docs, while a security-auditor agent might get read-only file access and a model chosen for careful reasoning over speed. You can configure custom agents in JSON inside your OpenCode config or as standalone Markdown files, and once defined, they show up alongside Build and Plan when you cycle through agents with the Tab key, or you can invoke one directly with an @ mention. The full options list, covering things like max steps, tool restrictions, and per-agent model overrides, is in OpenCode’s agents documentation.
Keybinds are just as customizable, through a separate tui.json file placed next to your opencode.json. Here’s a small example that changes the leader key and remaps a couple of session commands:
// tui.json
{
"$schema": "https://opencode.ai/tui.json",
"leader_timeout": 2000,
"keybinds": {
"leader": "ctrl+x",
"session_new": "<leader>n",
"session_list": "<leader>l",
"model_list": "<leader>m"
}
}You don’t need to memorize the full binding set, but a few of the defaults are worth knowing before you start remapping anything:
| Action | Default Keybind |
|---|---|
| Leader key | ctrl+x |
| Command palette | ctrl+p |
| Cycle primary agent | tab (shift+tab to reverse) |
| New session | <leader>n |
| List sessions | <leader>l |
| List models | <leader>m |
| Interrupt the agent | escape |
| Undo / redo last change | <leader>u / <leader>r |
Step 12: Install the IDE Extension for VS Code, Cursor, or Windsurf
If you spend most of your day in an editor rather than a standalone terminal, OpenCode’s IDE extension brings the same agent into VS Code, Cursor, Windsurf, or VSCodium. Installation is close to automatic: open the editor’s integrated terminal and run opencode as usual. The extension installs itself the first time it detects a supported editor’s terminal environment.
Once it’s installed, a few shortcuts make the round trip between editor and agent faster:
- Quick Launch:
Cmd+Escon Mac,Ctrl+Escon Windows/Linux, opens OpenCode in a split terminal view or focuses an existing session - New Session:
Cmd+Shift+Escon Mac,Ctrl+Shift+Escon Windows/Linux, starts a fresh OpenCode session even if one is already open - File Reference:
Cmd+Option+Kon Mac,Alt+Ctrl+Kon Windows/Linux, inserts a reference to your current selection, such as@File#L37-42
The extension also picks up context automatically, sharing whatever file or selection you have active. If the automatic install doesn’t trigger, open your editor’s Extension Marketplace, search for “OpenCode,” and install it manually. This is also the step where a broader debate applies: an IDE-native experience like this one is closer to how tools such as Cline operate day to day, while OpenCode’s terminal-first design (with the IDE extension as an option, not a requirement) is closer to how Gemini CLI is built. Which one fits depends on whether you think in files-and-tabs or in a single running session.
Step 13: Complete Working Project — Ship a Real Feature End to End
Reading about slash commands only gets you so far. Here’s a full pass through OpenCode on a small, realistic task: adding rate limiting to a basic Express API. Start from any existing Node.js project with an Express server, or scaffold a throwaway one:
mkdir rate-limit-demo && cd rate-limit-demo
npm init -y
npm install express
git init && git add -A && git commit -m "initial commit"
opencodeInside OpenCode, run /init once so it has an AGENTS.md to work from. Then switch to Plan mode with Tab and describe the feature in plain language:
We need rate limiting on our Express API. Limit each IP to 100
requests per 15 minutes on all routes. Return a 429 with a clear
JSON error message when the limit is hit. Use a well-maintained
npm package rather than writing the logic from scratch, and add
a short test that confirms the 429 behavior.OpenCode will typically come back with a short plan: install express-rate-limit, wire it up as middleware in your app’s entry file, configure the window and max-request values, and add a test that fires more than 100 requests and checks for the 429. Read the plan, ask follow-up questions if anything looks off (for example, whether the limit should apply per-route or globally), and once you’re satisfied, hit Tab to switch to Build mode:
Looks good. Go ahead and implement it.In Build mode, OpenCode installs the dependency, edits your server file, and writes the test, showing you a diff for each change as it happens. A typical resulting middleware addition looks something like this:
const rateLimit = require('express-rate-limit');
const apiLimiter = rateLimit({
windowMs: 15 * 60 * 1000,
max: 100,
message: { error: 'Too many requests, please try again later.' }
});
app.use(apiLimiter);Run your test suite the normal way for your project (for example npm test) to confirm OpenCode’s changes actually pass. If something’s off, don’t manually patch it. Tell OpenCode what’s wrong in plain language and let it correct its own work, or fall back to /undo if you’d rather start the request over. Once everything passes, review the diff one more time, commit it, and optionally run /share to generate a link if you want a teammate to review the conversation that produced the change, not just the final diff.
That loop, plan, review, build, verify, commit, is the whole workflow. Everything else in this guide (providers, MCP servers, custom agents) is about making that loop faster or more capable, not replacing it.
How OpenCode Compares to Other Open-Source AI Coding Assistants
OpenCode isn’t the only open-source AI coding assistant worth knowing about, and it isn’t the right fit for every workflow. Here’s how it stacks up against the other names that come up most often, using GitHub star counts pulled directly from each project’s repository at the time of writing.
| Tool | GitHub Stars | License | Interface | Local Models |
|---|---|---|---|---|
| OpenCode | ~194,000 | MIT | Terminal, desktop app, IDE extension | Yes (Ollama) |
| Gemini CLI | ~106,000 | Apache-2.0 | Terminal | Limited |
| OpenAI Codex CLI | ~104,000 | Apache-2.0 | Terminal | No |
| Cline | ~66,000 | Apache-2.0 | IDE extension (VS Code-based) | Yes |
| Aider | ~48,000 | Apache-2.0 | Terminal, Git-native | Yes (Ollama) |
| Continue | ~35,000 | Apache-2.0 | IDE extension (VS Code, JetBrains) | Yes |
A few patterns fall out of that table. If you live in a code editor and rarely touch a bare terminal, Cline or Continue will feel more native since both are built as IDE extensions first. If you want a tool that’s genuinely terminal-only and leans hard into Git-based workflows, Aider’s design philosophy is worth a look, its standout feature is treating every AI-generated change as its own Git commit automatically. If you specifically want Google’s or OpenAI’s own first-party CLI experience rather than a third-party agent, Gemini CLI and Codex CLI are the official options, though neither currently matches OpenCode’s provider flexibility since both are built around their parent company’s models first.
OpenCode’s pitch is being the generalist: terminal-first like Aider and Gemini CLI, but also available as an IDE extension like Cline, and provider-agnostic in a way none of the single-vendor CLIs can match. That flexibility is also reflected in its star count, which sits well ahead of the field. For a deeper look at how OpenCode specifically stacks up against the current market leader on cost and adoption, see our OpenCode vs. Claude Code comparison, and for a wider view across the category, our roundup of the best AI coding assistants covers closed-source tools too.
5 Common Pitfalls When Setting Up OpenCode
Most OpenCode setup problems trace back to one of these five mistakes. Catching them early saves a lot of confused debugging later.
- Skipping /init and never committing AGENTS.md. Without it, OpenCode has to re-infer your project’s structure and conventions every single session, which produces less consistent results and slower first responses. Run it once per project and commit the file.
- Enabling every MCP server you find. Each one adds its tool definitions to the model’s context window before you’ve typed a single prompt. A GitHub MCP server alone can consume a large chunk of your context budget. Enable only what a given project actually needs.
- Defaulting to Build mode for large, ambiguous changes. Build mode has no guardrails by design, it can edit files and run shell commands immediately. For anything bigger than a small fix, plan first, review the plan, then build.
- Installing natively on Windows and expecting IDE-parity performance. OpenCode’s own documentation recommends WSL for a reason. Native Windows installs work, but terminal rendering and some features are noticeably rougher without it.
- Not setting a provider blacklist or whitelist. Leaving every model from a connected provider visible in the
/modelspicker makes it easy to accidentally select an expensive model for a routine task. A few minutes configuringwhitelistin your provider config prevents surprise bills.
Troubleshooting: 8 Common OpenCode Problems and Fixes
If something breaks during your opencode install or setup, check the logs before anything else. OpenCode writes timestamped log files to ~/.local/share/opencode/log/ on macOS and Linux, keeping the ten most recent runs, and you can get more detail by launching with opencode --log-level DEBUG. On Windows, the same directory lives at %USERPROFILE%\.local\share\opencode\log. Beyond that, here are the issues that come up most often.
| Problem | Likely Cause | Fix |
|---|---|---|
| “opencode: command not found” | Shell hasn’t picked up the updated PATH | Close and reopen your terminal, or manually source your shell profile |
| IDE extension doesn’t auto-install | Editor’s CLI command isn’t on PATH | Run “Shell Command: Install ‘code’ command in PATH” (or your editor’s equivalent) from the command palette |
| Tool calls silently fail on a local model | Ollama’s context window is too small | Increase num_ctx to 16,000–32,000 in your Ollama model config |
| Sessions feel slow or responses get cut off | Too many MCP servers enabled at once, eating context | Set enabled: false on MCP servers you’re not actively using |
| Desktop app UI is blank or frozen | Stuck webview or a bad cached state | On macOS, use OpenCode menu → Reload Webview. Otherwise fully quit and relaunch |
| Desktop app crashes on launch | A misbehaving plugin | Set "plugin": [] in your global config to temporarily disable plugins, then re-enable one at a time |
| “Invalid API key” after /connect | Key copied incorrectly, or billing not added at opencode.ai/auth | Re-run /connect and paste the key again, confirming billing details were saved |
| Config changes don’t seem to apply | Wrong file location, or a higher-precedence config is overriding it | Confirm you edited the right file (global vs. project) and remember project config wins on conflicting keys |
If none of these match what you’re seeing, clearing OpenCode’s cache is the next step for desktop app issues (delete ~/.cache/opencode on macOS and Linux, or the equivalent under %USERPROFILE% on Windows), and a clean uninstall via opencode uninstall is the last resort for a CLI install that’s stuck in a bad state.
Advanced Tips for Power Users
Once the basic opencode setup is solid, a few features are worth exploring for anyone using it daily or across a team.
Scripted and Headless Usage
OpenCode isn’t limited to the interactive TUI. The opencode run command accepts a prompt directly, which is useful for CI pipelines or scripted workflows where you want an agent to make a specific, bounded change without a human watching the terminal:
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Update the changelog with today's merged PRs"Combine this with the OPENCODE_CONFIG and OPENCODE_CONFIG_DIR environment variables to point automated runs at a config and agent set that’s different from what you use interactively, keeping CI permissions tighter than your local setup.
Organization-Wide Defaults
Larger teams can publish default configuration, including pre-approved MCP servers, from a .well-known/opencode endpoint. OpenCode fetches this automatically when a developer authenticates with a supporting provider, and it’s loaded as the base layer beneath global and project config, so individual developers can still override specific settings without losing the shared baseline.
Building on Top of OpenCode
For teams that want to go further than configuration, OpenCode exposes an SDK, a server mode, and a plugin system, documented under the “Develop” section of its docs. That’s the path for anything from a custom internal dashboard over OpenCode sessions to a plugin that enforces org-specific coding standards before a change is allowed to land.
Frequently Asked Questions About OpenCode Setup
Is OpenCode really free?
The tool itself is free and MIT licensed, with no subscription required to install or run it. You pay your chosen model provider directly for token usage, or pay nothing at all by running local models through Ollama. Optional paid add-ons like OpenCode Zen and OpenCode Go exist for convenience but are never required.
Do I need to be an experienced developer to use OpenCode?
It helps. OpenCode is a terminal-first tool, so comfort with a command line and basic Git workflow makes the learning curve much shorter. Beginners can still use it through the VS Code extension, which softens the terminal-only feel, but the underlying interaction model (plan, review, build) assumes some familiarity with reading a code diff.
Can I use OpenCode completely offline?
Yes, if you connect a local model through Ollama as shown in Step 9. Cloud providers like Anthropic, OpenAI, or Google obviously require an internet connection, but a fully local setup works on a plane with no signal.
Does OpenCode work well on Windows?
Yes, but with a caveat: OpenCode’s own documentation recommends Windows Subsystem for Linux (WSL) for the best experience, citing better performance and full feature compatibility. Native installs through Chocolatey, Scoop, or npm work fine for basic use, but expect rougher terminal rendering without WSL.
What’s the difference between OpenCode Zen and OpenCode Go?
OpenCode Zen is a curated, pay-as-you-go list of models the OpenCode team has tested directly against their agent. OpenCode Go is a low-cost subscription plan covering popular open coding models. Both are optional convenience layers on top of the 75-plus providers OpenCode already supports, not requirements.
How does OpenCode compare to Claude Code?
The core difference is licensing and provider flexibility: OpenCode is open-source, MIT licensed, and works with any of 75-plus providers including local models, while Claude Code is Anthropic’s own tool built specifically around Claude models. Our full OpenCode vs. Claude Code comparison covers pricing and adoption numbers in detail.
Can my whole team share the same OpenCode configuration?
Yes. Check a project-level opencode.json into your repository so every teammate who clones it inherits the same model defaults, MCP servers, and agent permissions. For company-wide policy, publish defaults through a .well-known/opencode endpoint, which OpenCode picks up automatically on authentication.
Is my code sent anywhere besides my chosen AI provider?
No. OpenCode stores your provider credentials locally in ~/.local/share/opencode/auth.json and routes your prompts and code context directly to whichever provider you’ve configured, the same way any API client would. Conversations are only shared externally if you explicitly run /share, which is opt-in every time and not enabled by default.
Related Coverage
- OpenCode vs Claude Code: Free vs $20, 5.4x Downloads [2026]
- Gemini CLI vs Claude Code: Free Tier Gone, $200 Cap [2026]
- Cline vs Claude Code vs Copilot: Free vs $20 vs $10 [2026]
- Claude Code vs Codex: 23% Higher Cost Per Task [2026]
- How to Set Up GitHub Copilot: 12 Steps, 70 Min [2026]
- Best AI Coding Assistants 2026: 7 Tools Ranked by Speed, Price & IDE Support
- Kiro vs Claude Code: 80.8% SWE-bench, $200 Cap [2026]
