OpenCode

OpenCode is a free, MIT-licensed coding agent that runs as a terminal app, a desktop app and an IDE extension, and talks to 75+ model providers, including local models. You can bring your own keys or subscriptions, or buy tokens through its own Zen service. Checked 31 October 2026.

At a glance

What it is

OpenCode calls itself "the open source AI coding agent". The pitch is independence. You are not tied to one vendor's model, one vendor's login or one vendor's editor. The site's own numbers (220K+ GitHub stars, 950 contributors, 20,000+ commits, "16M+ developers per month") describe a very large project; treat the monthly figure as the site's claim, not a measured fact.

Day to day it looks like other terminal agents: you open it in a project, describe the work, and approve edits and commands. The differences are in the plumbing. Models come from a registry, not a single vendor, and you can run several agents in parallel on one project.

Install

The README lists many routes.

# install script
curl -fsSL https://opencode.ai/v2/install | bash

# package managers
npm i -g @opencode/cli@latest
brew install anomalyco/tap/opencode-v2
brew install opencode
sudo pacman -S opencode
mise use -g opencode
nix run github:anomalyco/opencode

One thing to watch: the project has a version 1 and a version 2. The README tip says to remove versions older than 0.1.x before installing, and the docs getting-started page says its install script and some package commands provide "OpenCode 1, which conflicts with OpenCode 2." The README's v2 install path and the docs page use different URLs, so check which one you are on before you file a bug.

The install script puts the program in $HOME/.opencode/bin.

The desktop app is still beta:

On macOS you can also run brew install --cask opencode-desktop.

First run

The docs give four steps.

1. Install it.
2. Run /connect inside the terminal UI and pick a provider. For OpenCode's own service you choose "opencode", sign in at opencode.ai/auth, add billing details, and paste the API key. You can pick a different provider instead.
3. Go to your project and run opencode.
4. Run /init. It analyzes the project and writes an AGENTS.md in the root. The docs suggest committing that file.

Then two habits worth forming:

• Plan before build. Press Tab to switch between the build agent (default, full access) and the plan agent, which denies file edits by default and asks before running bash commands. The docs recommend plan mode for exploring a codebase you do not know.
• Undo is a command. /undo reverts the latest changes and restores your message so you can reword the prompt. /redo reapplies them.

Models and providers

This is OpenCode's main selling point. It supports "75+ LLM providers through Models.dev, including local models." The site names Claude, GPT and Gemini and, in the FAQ, OpenAI, Anthropic and xAI.

You have three ways to pay for models:

Zen pricing

Zen charges per request against credits you add, with prices listed per million tokens. A few rows we confirmed on the Zen page:

The page lists many more models, with tiered rates for long contexts, and says a processing fee is added to each credit purchase. It also describes auto-recharge and monthly budgets per workspace and per member.

Free models on Zen are available "for a limited time", so the list changes. When we checked it included several flash-size models from different labs. You can hide them with OPENCODE_DISABLE_FREE_MODELS=1.

MCP, rules and extensions

OpenCode takes MCP servers in its config under the mcp key, local or remote:

{
  "mcp": {
    "my-remote-mcp": { "type": "remote", "url": "https://my-mcp-server.com", "enabled": true }
  }
}

Rules live in AGENTS.md, which is why switching between OpenCode and other agents costs little: Claude Code and Codex CLI read the same file or can be pointed at it. Good first servers are Context7 for current docs and GitHub MCP. See also MCP clients.

Privacy and data handling

The site says: "OpenCode does not store any of your code or context data, so that it can operate in privacy sensitive environments." The FAQ adds that your data "is only stored when you use our free models."

The Zen page is more detailed.

So the rule is simple: paid Zen models and your own keys are the private route. Free models are for code you would be happy to share. If you connect a provider yourself, that provider's policy applies instead.

Limits

• It is only as good as the model you point it at. A weak free model will not behave like a top model, and OpenCode cannot change that.
• Two major versions exist, with a conflict between them, so installs from old guides can break.
• The desktop app is beta.
• Free model lists change without notice.
• Hooks are not described in the pages we read. Skills and custom agents are documented, and covered below.

Permissions you should set on day one

OpenCode decides each action with three answers: allow runs without asking, ask prompts you, and deny blocks it. The permissions page says the old boolean tools setting is deprecated and has been merged into permission. Rules match by pattern, a * matches any run of characters, and the last matching rule wins, so put the catch-all first and the exceptions after it.

A cautious configuration for a real repository, in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "npm test*": "allow",
      "rm *": "deny"
    },
    "edit": "ask",
    "webfetch": "ask"
  }
}

This reads and searches freely, asks before edits, web fetches and unknown shell commands, lets a short list of safe commands through, and refuses deletion. It also pays to remember two behaviours from the docs. The --auto flag approves every request that is not explicitly denied, so deny rules still bite, but anything that would have asked now runs, so use it only in a throwaway environment. And paths outside the folder where you started need an external_directory rule, even if you spelled them with ~.

The built-in plan agent comes with edits denied. The docs warn that your top-level rules apply to it too, because the last matching rule wins, so a global "edit": "allow" also unlocks Plan. If you want Plan to stay read-only whatever you set globally, give it its own permission block under agent.plan.

Skills and custom agents

Both are documented, so OpenCode is more extensible than its short feature list suggests.

Skills. A skill is a folder with a SKILL.md file, loaded on demand through a native skill tool. OpenCode looks in .opencode/skills/<name>/SKILL.md for a project, in ~/.config/opencode/skills/<name>/SKILL.md for you, and also in the Claude-compatible .claude/skills/ and agent-compatible .agents/skills/ folders, both project and global. That means a skills folder written for Claude Code works here unchanged, which is the cheapest way to try the tool with your existing setup. Skills can be allowed, asked or denied through the same permission settings, and overridden per agent. See skills for the format.

Custom agents. The agents page describes primary agents you switch between with Tab, and subagents you invoke for a task. Built in are build, plan, general (full tools apart from todo writing, for parallel work) and explore (fast and read-only), plus hidden helpers that compact context and write titles. You define your own in JSON config or as markdown files, with a description, model, temperature, step limit and per-agent permissions. A reviewer that can only read and a docs writer that can edit only *.md files are the typical first two, and the permission block above is how you enforce that, not just ask for it. See subagents for the wider idea.

Choosing a model route, with numbers

The billing route matters more here than in a single-vendor tool. Zen lists Claude Sonnet 5.5 at $2 input and $10 output per million tokens, and Claude Opus 5 at $5 and $25. Using the same illustrative volumes we use elsewhere on this site, here is what a month looks like on Zen, before the processing fee on credit purchases. The token counts are assumptions.

Compare that with a flat subscription route, such as signing in with a ChatGPT plan or a GitHub Copilot seat, which OpenCode also supports. A flat plan is cheaper at heavy use if its limits hold, and per-token billing is cheaper at light use. That is the main reason to try both routes for a week, one task at a time, and read the usage numbers. Free models cost nothing but carry the retention caveats in the privacy table, so keep private code away from them. For other vendors' prices, see LLM API prices.

Configuration worth knowing

The config page lists the sources in load order, with later ones overriding earlier ones: remote organizational defaults from a .well-known/opencode endpoint, your global file at ~/.config/opencode/opencode.json, a file named by the OPENCODE_CONFIG variable, the project's opencode.json, the .opencode folders for agents, commands and plugins, an inline OPENCODE_CONFIG_CONTENT variable, and finally managed files that an administrator controls and a user cannot override. That makes a sensible split: put model and theme preferences in the global file, put permissions and MCP servers in the project file so teammates share them, and use the managed layer for anything a company must enforce. Add the $schema line at the top of each file, as in the examples, and an editor will validate keys as you type. Commit the project file and AGENTS.md, and keep API keys out of both, using environment variables or the /connect flow.

A sensible first week

Because OpenCode lets you change nearly everything, a short plan keeps you from drifting.

The last step is the one only a multi-provider agent allows. If the second model gives a much better result, the lesson is about the model, and you can keep the agent.

Parallel sessions

The site lists multi-session work: "Start multiple agents in parallel on the same project." Two cautions apply to any tool that does this. Agents editing the same files will conflict, so give each one a separate task or a separate branch. And parallel runs multiply token use, which matters if you pay per token through Zen or your own key.

Common questions

Is OpenCode affiliated with the models it runs? No. It routes to providers. The README asks projects built on it that use "opencode" in their name to say they are not made by the OpenCode team.

Can it run fully offline? It supports local models, so a local setup is possible. How good that is depends on the model you run.

Do I need an account? The site says free models work without one. Zen and the sign-in routes need accounts.

Which license covers my output? The tool is MIT. Your code remains yours; the model provider's terms govern anything about outputs.

Why does the README mention a Zen account? The OpenCode site suggests it as the simplest route to popular coding models, since one balance covers several vendors. The trade-off is a processing fee on credit purchases and the retention rules in the privacy table above.

Can a team share one setup? The Zen page describes workspaces: owners and admins invite members, a Models tab controls which models are on, budgets cap spending per workspace and per member, and teams can connect their own providers.

Who it suits

• People who want an open-source agent they can inspect and fork.
• Anyone who wants to switch models often or compare vendors on the same task.
• Teams that want to reuse Copilot or ChatGPT seats.
• Privacy-minded users who can run local models.

It suits less well if you want one vendor to own the whole stack and the support line.

Moving to it from another agent

1. Keep your instruction file: OpenCode reads AGENTS.md. If you only have a CLAUDE.md, run /init and merge in the content.
2. Re-create MCP servers in the mcp config.
3. Connect the provider you used before, so any behavior difference comes from the agent and not the model.
4. Use plan first on the new repository, then build.

Alternatives and duos

Our take

This is based on the OpenCode site, README and Zen pages. We did not run a test for this page.

OpenCode answers a question the big vendors cannot: what if you want a good agent loop without a model marriage? Its provider coverage, MIT license and the plan/build split are the reasons to look at it. The project is also clearly alive, with a push the day before we checked.

The caution is that freedom brings choices. You have to pick a model, a billing route and an install path, and the two-version situation shows the project moves quickly. If you value a single supported setup, a vendor agent is simpler. If you value choice, install OpenCode and try one repository with plan mode first.

Checklist

• Check which version you installed and which docs match it
• Run /connect and choose your billing route on purpose
• Run /init and commit AGENTS.md
• Start in plan mode on an unfamiliar repository
• Do not send private code to free models
• Add one MCP server under mcp