How to Use OpenCode: Setup, Providers & Models 2026
%3C/text%3E%3C/g%3E%3C/svg%3E)
If you want to know how to use OpenCode, the workflow comes down to four moves: install the tool, connect a model provider, let it create an AGENTS.md file for your project, then drive the build and plan agents. OpenCode is an open-source AI coding agent that lives in your terminal, built by Anomaly and released under the MIT license. It runs as a terminal interface, a desktop app in beta, and an IDE extension, with a built-in agent that reads your repository, edits files, and runs commands. The part that surprises newcomers is the model: the tool ships none of its own and charges nothing for tokens. It is bring-your-own-key, so you connect a provider you already pay for, and all model spend goes to that provider, not to the agent itself. This guide walks the full path: installing it, connecting a provider with opencode auth login, configuring opencode.json and an AGENTS.md file, using the build and plan agents, running parallel sessions, and adding MCP servers.
Before anything else: OpenCode the software is free and open-source. There is no subscription to use it and no inherent model cost. Because it is bring-your-own-key, your only spend is what your chosen LLM provider charges for the tokens you use. We make that cost model explicit throughout, so you do not expect a single flat fee.
How to Use OpenCode: What You Need First
Learning how to use OpenCode takes two decisions, not one. First you install the tool, which is quick. Then you decide which model provider to point it at, because the agent does not come with a model. That second decision is where the real choice lives, and it is worth settling before you open your first session rather than mid-task.
One thing to settle early: OpenCode is privacy-first and, per its own documentation, does not store your code or context data. Even so, the model provider you connect has its own data and retention terms. Pick a provider whose handling you are comfortable with before you run the agent against private code.
Install OpenCode
There are several ways to install OpenCode, and the right one depends on your platform and the tools you already use. The install script is the simplest path on macOS and Linux, but package managers give you a route that fits your existing toolchain.
If you would rather install through a package manager, OpenCode is published to the common ones. Pick whichever matches how you manage other developer tools.
| Platform | How to install |
|---|---|
| Node / npm | Install the package with npm, Bun, pnpm, or Yarn, whichever you already use |
| macOS | Homebrew via the OpenCode tap, or the install script above |
| Arch Linux | Available through the AUR with an AUR helper such as paru |
| Windows | Run under WSL (recommended), or use Chocolatey, Scoop, Mise, or Docker |
| Desktop | A desktop app is in beta for macOS, Windows, and Linux |
On Windows: the documentation recommends running OpenCode under the Windows Subsystem for Linux. The native package-manager and Docker routes exist, but a WSL environment most closely matches the Unix terminal the tool is designed around.
Once it is installed, you launch OpenCode by running opencode inside a project folder. The first thing it will need is a model provider, which is the next step.
Connect a Provider
OpenCode does not ship a model. Instead it connects to providers you choose, through the AI SDK and the Models.dev catalog, which covers more than 75 providers including Anthropic, OpenAI, DeepSeek, Google Vertex, Amazon Bedrock, and Groq, as well as local models run through Ollama, LM Studio, or llama.cpp. That is the source of the tool's flexibility, and the reason cost is entirely a function of which provider you pick.
Adding a provider
You connect a provider in one of two equivalent ways. From inside the terminal interface, run the /connect command. From a shell, run the auth command directly.
Either route walks you through selecting a provider and entering its credentials. Those credentials are written to an auth.json file, by default at ~/.local/share/opencode/auth.json. Treat that file like any other secret on your machine.
The three routes to a model
Beyond a raw provider key, OpenCode gives you a couple of managed options. Which one fits depends on whether you already pay for an AI subscription and how hands-on you want to be about model choice.
| Route | What it is and what it costs |
|---|---|
| Bring your own key | Add an API key for any of the 75+ supported providers. You pay that provider directly for the tokens you use. |
| OpenCode Zen | A curated set of coding models that the OpenCode team has tested, billed pay-as-you-go. The default helper model, gpt-5-nano, is served through Zen. |
| OpenCode Go | A low-cost subscription option for those who prefer a flat-rate plan over per-token billing. |
| Link a subscription | Connect an existing ChatGPT Plus or Pro, GitHub Copilot, or GitLab Duo subscription at no extra cost beyond what you already pay. |
Configure and Init AGENTS.md
With a provider connected, the next step is letting OpenCode learn your project. When you run it in a repository, it can create an AGENTS.md file: a plain-text record of your project's conventions and context that the agent reads before it works. Think of it as the place to write down the things you would otherwise repeat in every prompt, such as how the project is structured, which commands to run, and the conventions you expect code to follow.
Configuration lives separately, in an opencode.json file at the project root, or globally in ~/.config/opencode/opencode.jsonc. This is where you set defaults such as the model to use, provider options, and other behavior, so you do not have to pass them on every run.
If you already use Claude Code: OpenCode reads existing Claude Code configuration, including .claude files, CLAUDE.md, and skills, so an existing setup carries over. You can turn that behavior off with the OPENCODE_DISABLE_CLAUDE_CODE environment variables if you would rather keep the two separate.
For a first session you do not need to hand-write either file. Let OpenCode create the AGENTS.md, look it over, and add a line or two about anything specific to your project. The configuration file can stay empty until you have a setting you actually want to change.
Build and Plan Agents
OpenCode ships with a small set of built-in agents, and the two you will use day to day are build and plan. The build agent is the default. It has full access: it can read your code, edit files, and run commands, and it is what you use to actually make changes. The plan agent is read-only. It can analyze the codebase and propose an approach without touching anything, which makes it the safer way to ask what would you do here before you let the agent act.
You switch between them inside the terminal interface with the Tab key. A general subagent is also available for delegated work, and you can define your own with opencode agent create when you have a repeatable task that deserves its own configuration.
The editing loop
Working with the build agent is a loop of asking, reviewing, and adjusting. Two commands make that loop forgiving. /undo steps a change back, and /redo reapplies it, so you can experiment without fear of losing a good state. The interface also accepts drag-and-dropped images, which is useful when the task is easier to show than to describe, such as a screenshot of a layout bug.
OpenCode is also LSP-enabled: it auto-loads the language servers for your project, so the agent has the same structural understanding of your code that your editor's tooling does, rather than treating files as plain text.
| Step | What You Do |
|---|---|
| 1. Install | Install OpenCode with the script or a package manager and run it in your repo |
| 2. Connect | Run opencode auth login or /connect to add a model provider |
| 3. Init | Let OpenCode create an AGENTS.md and note any project conventions |
| 4. Plan | Switch with Tab to the read-only plan agent to scope a change first |
| 5. Build | Use the build agent to make the change, reviewing with /undo and /redo |
Sessions and Editing
OpenCode organizes work into sessions, and it can run more than one in parallel. That lets you keep several independent lines of work going at once, the way you might keep separate terminal tabs open, rather than serializing everything through a single conversation.
Two flags shape how sessions relate to each other. You can --continue a previous session to pick up where you left off, or --fork one to branch from its current state into a new thread without disturbing the original. Sessions can also be exported and imported as JSON, which is how you hand one off, archive it, or move it between machines.
For a first session, keep it simple: one session, one well-scoped task. Ask the build agent to make a small, contained change you can read through in a few minutes, review what it did, and accept or undo. Parallel sessions and forking earn their place once you trust the basic loop and have more than one thing in flight.
A practical habit: use the plan agent in one session to think through a larger change while a build agent in another session handles a small, unrelated fix. Because OpenCode keeps sessions separate, the read-only analysis and the live edits do not interfere with each other.
Add MCP Servers
Once the core loop feels comfortable, you can extend OpenCode beyond the repository. It supports the Model Context Protocol, an open standard for giving an AI tool access to external systems and data sources. Connecting MCP servers lets the agent pull in context and act on tools beyond the files in front of it, reaching the services you already use.
The opencode mcp add command registers a server, and opencode mcp list shows what is connected. Once a server is wired in, its tools become available to the agent during a session, the same way the built-in file and command tools are.
You do not need any of this on day one. Start with the editor loop and a single provider, then add MCP servers when a specific need comes up, such as reaching an issue tracker or a documentation source, rather than wiring everything before you have a reason to.
Where to go next: that is the short version of how to use OpenCode end to end, from install to MCP. If you want the background on what the project is, who maintains it, and where it sits among coding tools, read our companion breakdown, What Is OpenCode?
Troubleshooting
When people first work out how to use OpenCode, the same handful of questions come up. Here is the practical answer for each.