OpenCode: install, providers, config, agents, MCP and skills

What is OpenCode?

OpenCode is an open source AI coding agent that runs in your terminal, as a desktop app or in the browser, and works with models from almost any provider. You install the opencode command, connect a provider with /connect, and ask it to read, plan and change code in your project. The code is on GitHub at anomalyco/opencode under the MIT license.

Its main draw is model choice. The OpenCode site says it supports "75+ LLM providers through Models.dev, including local models," and lets you sign in with an existing ChatGPT Plus or Pro plan or a GitHub Copilot account.

One thing to know first: there are two major versions. OpenCode 2 is what the home page installs today, while the docs at opencode.ai/docs still describe OpenCode 1. This guide follows the OpenCode 2 docs as of 24 October 2026 and calls out V1 differences where they matter.

How do you install OpenCode?

The quickest path is the install script:

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

Package managers work too:

brew install anomalyco/tap/opencode-v2
npm install -g @opencode/cli

The V2 docs say Windows package managers are not supported; download a standalone CLI binary from the intro page instead. Desktop builds are listed for macOS, Windows and Linux.

If you already run OpenCode 1, read this before installing. Both versions use the opencode command and "are no longer installed side by side by default." The migration guide says to remove a package-managed V1 install first; the V2 curl installer replaces the V1 binary. The V1 commands, for reference, are curl -fsSL https://opencode.ai/install | bash, npm install -g opencode-ai and brew install anomalyco/tap/opencode. Note that Homebrew's own brew install opencode formula now installs V2.

Then open a project and start it:

cd my-project
opencode                              # full-screen terminal interface
opencode run "Explain this repository"  # one prompt, for scripts and CI

opencode mini starts a minimal interactive interface instead of the full-screen one, and opencode pair gives you access to the OpenCode web interface.

How do you connect a model provider?

Inside OpenCode, run /connect, pick a provider and enter its credentials, then run /models to choose a model. The catalog comes from models.dev, so most providers need no extra setup.

The providers page describes a few special cases:

As of October 2026, the Go page lists Go at $10 a month and Go Plus at $40 a month for access to a list of coding models, and says "you don’t need it to use OpenCode."

Keep keys out of config files by referencing environment variables:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "anthropic": {
      "settings": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  }
}

How does the opencode.json config work?

Create opencode.jsonc (comments allowed) or opencode.json and set only what you need. The $schema line gives you autocomplete in most editors.

OpenCode reads config from several places and merges them. From lowest to highest precedence, the config page lists:

1. Global: ~/.config/opencode/opencode.json(c)
2. Project: opencode.json(c) at the project root or .opencode/opencode.json(c), with deeper folders overriding parent folders
3. System: /Library/Application Support/opencode on macOS, /etc/opencode on Linux, %ProgramData%\opencode on Windows

System config overrides everything else, which is how companies enforce settings, and on macOS OpenCode also reads managed preferences deployed by MDM tools. Settings that do not conflict are kept from every file.

A small project config might look like this:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ],
  "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"]
}

Permissions in V2 are one ordered list of rules with an action, a resource and an effect of allow, ask or deny, and the permissions page says the last matching rule wins. Common actions are shell, edit, read, webfetch, subagent and skill. One change from V1 worth noting: the migration guide warns that V2 does not ask before touching paths outside the project unless you add an external_directory rule with ask.

How do agents work in OpenCode?

An agent is a named profile with its own system prompt, model and permissions. OpenCode 2 ships four visible built-in agents, per the agents page:

To add your own, write a Markdown file in .opencode/agents/<name>.md for one project or ~/.config/opencode/agents/<name>.md for all of them. The body becomes the system prompt:

---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
---
Review the current changes. List findings in severity order with file and line references.

Then ask the main agent: "Use the reviewer subagent to review my current changes." The mode can be primary, subagent or all, and the #high suffix selects a model variant. V1 frontmatter fields are deprecated; the agents page says not to use legacy fields like prompt, tools and maxSteps in new V2 agents.

How do you add MCP servers to OpenCode?

The CLI writes MCP entries for you:

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
opencode mcp list

Add --global to make a server available in every project. Remote servers use OAuth by default; if one shows "needs authentication," run /mcps inside OpenCode, select it and sign in.

By hand, servers go under mcp.servers with a type of local (a command over stdio) or remote (a Streamable HTTP URL):

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp"]
      }
    }
  }
}

This is a V2 change. In OpenCode 1, server names sat directly under mcp and used enabled instead of disabled. The MCP page also notes that MCP tools use model context, so add only the servers you need. For ideas, see the MCP servers roundup.

How do skills and AGENTS.md rules work?

OpenCode reads the same SKILL.md folders other agents use. The skills page lists these locations:

For project folders, OpenCode searches from your current directory up to the project root. At each step it shows the model only the ID, name and description of each skill, and the model loads the full body with its skill tool when it needs it. To force a skill, mention it as @skill-id in your prompt. A skill without a description is not advertised to the model at all.

Two details trip people up. The skill ID comes from the folder path, not the name field, so .opencode/skills/release/SKILL.md is release whatever its frontmatter says. And V2 does not enforce the Agent Skills naming rules, so keep IDs lowercase with hyphens, 1 to 64 characters, if you want them to work in other tools. The Agent Skills guide covers the full format, and Claude Code skills shows the same folders from Claude's side.

For always-on instructions, OpenCode uses AGENTS.md. It loads ~/.config/opencode/AGENTS.md plus every AGENTS.md from your current folder up toward your home folder, and picks up nested ones as the agent reads files deeper in the tree. The instructions page is direct about one limit: "OpenCode V2 recognizes AGENTS.md only. It does not use CLAUDE.md as a fallback." OpenCode 1 did fall back to CLAUDE.md when no AGENTS.md existed, and in OpenCode 1 the /init command creates or updates an AGENTS.md for you. See the AGENTS.md guide for what to put in it.

How do you share skills between OpenCode and other agents?

Put shared skills in .agents/skills/ or ~/.agents/skills/. OpenCode reads both, and so do several other agents, so one copy serves them all.

If your skills and prompts are spread across projects, Kipt keeps them as Markdown in a private GitHub repo you own, and imports skills from a GitHub link, a folder or a .zip. You can then install every skill into Claude Code or Codex with npx skills add https://github.com/<you>/<repo>.git --all -g, or copy folders into .agents/skills/ for OpenCode. The free SKILL.md generator turns a prompt into a valid skill file in the browser.