OpenCode: what it is, how to install it, and connect a model in 2026

OpenCode is an open-source AI coding agent for the terminal: the tool itself is free (MIT license), and you can connect any model—from Claude and GPT to a local one through Ollama. The project repository has already passed two hundred thousand stars on GitHub. The phrase “free Claude Code with any model” sounds appealing, but needs clarification: the tool is free; the terms of use depend on the model you choose.

Below is everything according to the official documentation: what the tool is, how to install it on macOS, Linux, or Windows, how to connect a model, and what to do on first launch. There is a separate section on costs, because “free” here applies only to the tool: models cost money, and that is what most often causes confusion.

Practical information about working with Ailoot is in the documentation.

What is OpenCode in simple terms?#

In short, OpenCode does the same thing as Claude Code: it accepts a task in plain language and carries it out in your project. They differ in two ways. The code is fully open, so you can read and inspect it. And the tool is not tied to a single model provider: it works with 75+ providers, from Anthropic and OpenAI to a local model running on your hardware.

The project is developed by the Anomaly team. The repository was created on April 30, 2025, and as of October 4, 2026, it has more than 211 thousand stars and 28 thousand forks (verified with a GitHub API request). The language is TypeScript. The documentation is continuously updated, so the instructions below are based on the current version.

Don’t confuse the names: the npm package for the current line is called opencode-ai, the repository is anomalyco/opencode, and the terminal command is simply opencode. Older articles may use the address sst/opencode: the organization changed its name, and the old link now redirects to the new one.

Updated October 4, 2026: the team released OpenCode 2.0, the next major generation of the tool. The installation and model connection instructions below are still written for the current 1.x line (installed with the command curl -fsSL https://opencode.ai/install | bash; the current version as of September 30, 2026 is 1.18.34): it is actively supported, and it is the version installed by the official documentation at opencode.ai/docs. What exactly changed in the second version and when to switch are covered in a separate section below.

How is OpenCode different from Claude Code and Codex?#

If you already have a Claude subscription, it makes sense to keep Claude Code as your main tool—we have a detailed installation guide about it. OpenCode makes sense in three cases: you want to work through a ChatGPT Plus or GitHub Copilot subscription, you want to run a local model without API bills, or you want a single interface for several models. We also have a review and installation guide for Codex.

If you’re still choosing a tool, start with this overview: what people code with in 2026. And if you already have OpenCode installed and need to connect it with other agents in Devin Desktop through ACP, see our guide to that setup.

What changed in OpenCode 2.0?#

The second version is installed with the command curl -fsSL https://opencode.ai/v2/install | bash. According to the official migration guide (opencode.ai/v2/docs/migrate-v1), both versions use the same opencode command and are no longer installed side by side by default: the v2 installer replaces the v1 binary, and before installing v2 through a package manager, the documentation explicitly asks you to remove version v1 first. However, configuration is read from the same files—~/.config/opencode/ and <project>/.opencode/—so settings, agents, and MCP servers transfer without rewriting. Three things do need rewriting: plugins (they have a new API), integrations with the server API (the protocol has changed), and terminal settings (now one shared cli.json file instead of several tui.json files).

The two most notable new features in v2 are these. First, Console was introduced—a paid service for teams with usage tracking, budgets, and shared policies for all members. Second, the team finally announced the price of the Go subscription: $10 per month for Go and $40 per month for Go Plus with higher limits (the opencode.ai/go page, verified October 4, 2026). Previously, the documentation simply said “low-cost subscription,” without a figure.

If you’re new and just want to install the agent, follow the instructions below; they cover the current first version recommended by the documentation itself. Consider v2 if you need the new plugin features or team Console—but be prepared to rewrite some older plugins for the new API. If you’re more interested in an open-source desktop application that doesn’t require a terminal, we have a review of ZCode, another similar agent with its own interface.

What do you need before installing?#

A little more about the terminal, because it’s the only place where installation may not go as planned. OpenCode renders a full interface with panels and highlighting in the terminal, which is why the documentation asks for a modern emulator. If the interface looks wrong after launch, first install one of the four named options: WezTerm (works on all systems), Alacritty, Ghostty, or Kitty. On Windows, the main route is through WSL; that has its own section below.

The second thing is a model. OpenCode works through the model you connect: by itself, it does not process requests. There are four options: a subscription (ChatGPT Plus, GitHub Copilot, GitLab Duo), an API key from any provider, OpenCode Zen, the aggregator from the team itself, or a local model through Ollama. All four options are covered in the section on connecting a model.

Without a project description, the agent has to guess the build commands, file structure, and conventions in use—hence the “hallucinations.” OpenCode uses an AGENTS.md file for this. The same approach applies to Claude Code and any other agent; only the name of the instruction file changes.

For an OpenCode install Mac users can run the native installer or Homebrew#

The recommended route is the official installer:

1. Run the installer

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

   The script detects your system and downloads OpenCode. If the command isn’t found after installation, close and reopen the terminal; the path will be picked up in the new session.

2. Check that it installed correctly

   opencode --version
   

   The command returns a version number, which means installation succeeded. The response “command not found” takes you back to the first step: start a new terminal session or edit PATH manually.

If you prefer managing packages yourself, here are the options:

brew install anomalyco/tap/opencode

npm install -g opencode-ai

The Homebrew command deliberately starts with anomalyco/tap/: the documentation recommends their own tap because the Homebrew team updates the formula for brew install opencode less often. The same package name, opencode-ai, also works with bun, pnpm, and yarn (bun install -g opencode-ai, yarn global add opencode-ai). On Arch Linux, use sudo pacman -S opencode from the stable repository or paru -S opencode-bin for the latest version from AUR.

Update OpenCode with opencode upgrade; when launched, it also downloads updates on its own if auto-update is enabled. After updating, check the version with the familiar opencode --version. Uninstallation is built in too:

opencode uninstall

The command shows exactly what will be deleted and asks for confirmation. You can keep configuration and session data if you want: use the --keep-config and --keep-data flags.

For an OpenCode install Windows users can choose WSL or a package manager#

The first option recommended by the developers themselves is WSL. Install it with one command in PowerShell running as administrator:

wsl --install

After rebooting, open Ubuntu from the Start menu and run the familiar command inside it:

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

Your files on Windows drives are available in WSL through /mnt/—drive C: is at /mnt/c/, and drive D: at /mnt/d/. So a project at C:\Users\Name\project can be opened like this:

cd /mnt/c/Users/Name/project
opencode

The second option is to skip WSL and use Windows package managers. In PowerShell:

choco install opencode

scoop install opencode

The third option is the desktop application and web version. The application installs like a regular program and displays the interface in a window, without a terminal. The web version starts with the opencode web command: it opens OpenCode in a browser, and the documentation recommends launching it from WSL too, to avoid problems accessing files. The documentation also lists less common options—mise, Docker, and a ready-made binary from the GitHub releases page. Installation through bun on Windows is still in progress; if bun is your main package manager, use the npm option.

How do you connect a model to OpenCode?#

OpenCode supports 75+ providers through the AI SDK and Models.dev, plus local models. Most are connected with the /connect command inside the interface; for local models, you also specify the server address in the config. The options differ in payment method and computer requirements:

The documentation recommends that beginners start with OpenCode Zen. The team selected models that work well specifically as agents and tested their combinations with providers on its own tasks.

Connecting works like this: enter /connect, choose OpenCode Zen, sign in and add payment at opencode.ai/auth, get a key, and paste it in. Then /models will show the list of recommended models. As of October 4, 2026, the list includes, for example, GPT 6.1 Sol, GPT 6 Astra, Claude Opus 5.5, Claude Sonnet 5, GLM 5.3, and Kimi K2.5. The documentation honestly warns that the list is not exhaustive and quickly becomes outdated because new models come out every week.

Subscriptions are connected with the same /connect command: choose ChatGPT Plus or GitHub Copilot from the list and sign in to your account—no extra setup is needed.

If you choose Anthropic, /connect offers two options: manually enter an API key, or choose Claude Pro/Max and authenticate through a browser. However, Anthropic prohibits third-party plugins for using a Claude Pro/Max subscription, and built-in plugins of this kind were removed from OpenCode starting with version 1.3.0. If you come across an older article about “OpenCode through a Claude subscription,” it refers to those removed plugins, not official authorization. ChatGPT Plus, GitHub Copilot, GitLab Duo (marked experimental), and Atomic Chat subscriptions work without extra setup.

OpenCode stores the keys you enter through /connect in the file ~/.local/share/opencode/auth.json. If you don’t want to choose a model each time, set the default model in the opencode.json config file at the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

The format is provider/model; both identifiers are shown in the /models output.

How do you connect a local model through Ollama?#

This option means no API bills at all: the model runs on your computer. If you’re choosing among free models in general, we have a separate review of which work reasonably well as agents and which only do so on paper. For OpenCode, install Ollama from the official site and download a model:

ollama pull qwen3-coder

A useful detail from the documentation: Ollama can configure itself for OpenCode automatically; it has a separate integration guide. If you want to set everything up manually, add a provider with the address of your local Ollama server to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Then /models in the interface will show the local model in the list. Select it and get to work. One practical caveat from the documentation: if the agent stops calling tools (editing files or running commands), increase num_ctx in Ollama settings—start with values of 16k–32k. Local models are weaker than cloud models specifically at agent work, and a small context makes that worse. If the local version isn’t enough, you can connect Qwen from the cloud with a key; where to get one is covered in the guide how to get an API key for Qwen Code.

How much does OpenCode and its use cost?#

All costs here are for the model, and there are four scenarios. With an API key or Zen, you pay for actual usage, and the amount depends on how much the agent works. Go is a subscription plan for open models from the OpenCode team: $10 per month for Go and $40 per month for Go Plus with higher limits (verified on the opencode.ai/go page on October 4, 2026). The limit depends on the model: for example, Go allows about 110 requests per 5 hours (440 per month) for Kimi K3 and about 26,000 requests per 5 hours for the lighter DeepSeek V4.1 Flash. For access to a specific model beyond the limit, the documentation lists a separate price ($15 per month for Kimi K3, $60 for Go Plus). See the subscription page when connecting for the full list of models and limits. With ChatGPT Plus or Copilot, requests are covered by the subscription you already pay for; just remember that subscriptions have their own intensity limits. Finally, requests to a local model through Ollama cost nothing—but you need a powerful enough computer to run it quickly.

After an OpenCode install Ubuntu users can open a project and start the first task#

First launch—inside your project folder:

cd path/to/project
opencode

The interface opens with an input field. First, use the /init command: the agent scans important repository files, asks a couple of questions if needed, and writes an AGENTS.md file—a guide to how the project is structured, which commands to run for builds and tests, and which conventions are used. The documentation recommends committing this file to git; OpenCode then uses it as a permanent project instruction. In purpose, AGENTS.md is a direct equivalent of CLAUDE.md in the OpenCode ecosystem.

Second, use Plan mode. The Tab key switches between the two main agents: Build works with full access to files and commands, while Plan is for analysis and planning—file edits and bash commands in Plan mode require your approval by default. For new tasks, the documentation recommends starting with a plan: read what the agent intends to do, adjust the wording, and only then switch back to Build with Tab.

The documentation offers this advice:

The more specific the task and the more context you provide, the less rework you’ll need. Add files to a request with @—start typing a name and the interface will find them with fuzzy search. You can drag images directly into the terminal, and a message that starts with ! runs as a shell command; its output is added to the agent’s context. If you made a mistake in the task or the agent did the wrong thing, /undo reverts the changes, and you can run it several times in a row. Changed your mind again? /redo restores what was undone. And /share creates a link to a conversation for your team; without this command, the conversation isn’t published anywhere.

In OpenCode install MCP servers, add custom commands, and use server mode#

Custom commands. Any recurring request can become a command: put a markdown file in .opencode/commands/, set description, agent, and model in its frontmatter, and write a prompt template below. Then call the command with /. Project checks before publishing, reviewing recent errors, generating a migration—anything you ask for regularly.

Subagents. Besides Build and Plan, there are three more: General for multi-step tasks (access to all tools except the task list), Explore for quickly reading code without permission to edit, and Scout for researching external libraries. Call them by mentioning them with @ in a message.

MCP servers. Connect external tools through the mcp section of the opencode.json config—both local and remote servers are supported. Each MCP server adds its tools to the context, and a greedy server like GitHub can use up context very quickly—connect selectively, only what you need. We have a guide with ready-made setups to the MCP concept; it’s written about Claude Code, but the protocol is shared.

Web version and server. opencode web opens the interface in a browser. For access from another machine, use opencode serve --hostname 0.0.0.0 --port 4096; whenever there is network access, be sure to set a password with the OPENCODE_SERVER_PASSWORD variable. Without a password, the server is unprotected.

What should you do if installation goes wrong?#

“opencode: command not found” after installation. The terminal doesn’t know about the new path yet. First, just close and reopen the terminal. If that doesn’t help, find where the installer put the binary and add that folder to your terminal’s PATH.

The model is silent or reports an authorization error. Check that the provider is connected: enter /connect and authenticate again. Keys are stored in ~/.local/share/opencode/auth.json—if you moved the installation from another machine or cleared folders, the file may be missing. The documentation covers the ProviderInitError and AI_APICallError errors separately: for the first, reauthorize the provider; for the second, clear the ~/.cache/opencode folder and restart.

The interface is broken: panels are scattered, or unreadable characters appear instead of symbols. Start by checking your terminal. Install one of the recommended options—WezTerm works on all three systems—and launch OpenCode from it.

If nothing helps, check the logs: on macOS and Linux they’re in ~/.local/share/opencode/log/; on Windows, press Win+R and enter %USERPROFILE%\.local\share\opencode\log. The ten most recent files are kept; enable detailed logging with the opencode --log-level DEBUG flag. With those logs, you can file a bug report in the project's GitHub repository.

What else do people ask about OpenCode?#

Open Ailoot.