What Is OpenCode? The Open-Source Terminal Coding Agent

OpenCode is an open-source AI coding agent. You run opencode in a project folder, connect a model provider, and describe what you want; it reads the code, edits files and runs commands, asking first where you have told it to. It is published by Anomaly under the MIT licence, works with more than 75 model providers as well as local models, and is built as a server with several clients: a terminal interface, a desktop app, an editor extension and a web interface. If you want a Claude Code-style agent that is not tied to one model vendor, and whose code you can read, that is what OpenCode is.

Who makes it

The OpenCode documentation is published by Anomaly, and the code is developed in the open in the anomalyco/opencode repository↗ (opens in a new tab) on GitHub, under the MIT licence. That licence lets you read, fork and modify it, and people do: the repository asks projects built on it to say clearly that they are not made by the OpenCode team. One well-known example is Kilo Code, whose CLI is built on OpenCode’s core; that family is covered in Cline, Roo Code and Kilo Code vs Claude Code.

Installing it

The install script is the quickest route on macOS and Linux. The OpenCode documentation↗ (opens in a new tab) also lists npm (opencode-ai), Homebrew (anomalyco/tap/opencode), Chocolatey and Scoop on Windows, the Arch package, and a Docker image at ghcr.io/anomalyco/opencode. On Windows the docs recommend running it under WSL for the best experience.

curl -fsSL https://opencode.ai/install | bash
# or: npm i -g opencode-ai
cd my-project
opencode

The TUI and the other clients

Running opencode starts a server and a terminal interface that talks to it. That split is what lets the same agent appear in several places. The CLI reference↗ (opens in a new tab) lists the commands that use it:

• opencode run "…" runs one prompt non-interactively, for scripts.
• opencode serve starts a headless server you can drive over HTTP from your own code.
• opencode web starts the server with a browser interface.
• opencode attach connects a terminal to a server that is already running, for example on another machine.
• opencode -c continues the last session; opencode session manages the rest, and opencode stats shows token use and cost.

Beyond the terminal there is a desktop app, in beta at the time of writing, for macOS, Windows and Linux, and an IDE extension. opencode github sets up an agent that works on your repository from GitHub itself.

Providers and models

OpenCode is not tied to one vendor. Inside the TUI, /connect adds a provider and stores its key in ~/.local/share/opencode/auth.json; /models switches model mid-session. The providers page lists more than 75, from Anthropic, OpenAI and Google to gateways and any OpenAI-compatible endpoint, plus local models through Ollama, LM Studio or llama.cpp. OpenCode Zen is the team’s own curated list of tested models, suggested for newcomers and entirely optional. Some subscriptions, such as GitHub Copilot and ChatGPT Plus or Pro, connect without an API key; Claude Pro and Max do not, and the reasons are set out in OpenCode vs Claude Code.

Agents: Build, Plan and your own

OpenCode’s agents documentation↗ (opens in a new tab) describes two primary agents, switched with Tab. Build is the default, with full tool access. Plan is for analysis: file edits and shell commands are set to ask, so it can read and propose without changing anything unless you approve. Three subagents are built in: General, with full tools, for multi-step jobs; Explore, read-only, for finding your way round a codebase; and Scout, read-only, for researching external docs and dependencies. The primary agent calls them when it needs them, or you name one with @, as in @explore where is the retry logic?.

Your own agents are Markdown files with frontmatter, in .opencode/agents/ for a project or ~/.config/opencode/agents/ for every project. Each can set its own description, mode, model, temperature and permissions, and opencode agent create walks you through writing one. A reviewer that can read but never edit looks like this:

---
description: Reviews a diff for bugs, missing tests and unclear names
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
---
Review the staged changes. List problems by file and line, most serious first.
Suggest the fix in words; do not rewrite the code yourself.

Call it with @reviewer once Build has finished a change. The pattern generalises: a narrow description plus narrow permissions keeps each agent to its job.

Config

Settings live in opencode.json or opencode.jsonc. The config documentation↗ (opens in a new tab) says files are merged rather than replaced, loading in order from a remote organisation config, the global ~/.config/opencode/opencode.json, a path in OPENCODE_CONFIG, the project’s own file and .opencode folders, up to admin-managed settings, with later sources winning a conflict. The main keys are model, provider, agent, permission, mcp, instructions and share, and values can pull from the environment with {env:NAME}. Add "$schema": "https://opencode.ai/config.json" and your editor will autocomplete the rest.

Permissions start permissive: most tools, including edits and shell commands, run without asking unless you say otherwise, while .env files are denied and paths outside the project ask. Set permission before your first real session if you want an agent that asks first. Project rules go in AGENTS.md, which /init writes for you; how that file compares with the others is in AI context files compared.

MCP

MCP servers go under the mcp key: type: "local" with a command array to start a process, or type: "remote" with a url and optional headers. opencode mcp auth <name> completes an OAuth sign-in in the browser, opencode mcp list shows what is connected, and opencode mcp logout clears a sign-in. The docs warn that every server’s tools add to the context, so switch off the ones you are not using.

Sharing a session

OpenCode can turn a conversation into a web page. The share documentation↗ (opens in a new tab) describes three modes: manual, the default, where /share creates a page for the current session and copies its address; auto, which shares every new session; and disabled. Shared sessions are publicly accessible to anyone with the address, so read what is in one before you share it, and /unshare removes it and deletes the data. For a team, set "share": "disabled" in the project config unless you have decided otherwise.

A first session

1. Install, cd into a project and run opencode.
2. Type /connect and add a provider: an API key, a supported subscription, or a local model.
3. Run /init. OpenCode reads the codebase and writes an AGENTS.md; read it, fix anything wrong and commit it.
4. Press Tab to switch to Plan and describe a small change. Read the plan it proposes.
5. Press Tab back to Build and let it make the change, then run the tests yourself.
6. When you are happy with the workflow, set permission and share in opencode.json and commit that too.

Keeping the work list outside the session

An OpenCode session knows what it did; your colleagues do not, and neither does the next session running a different model. A shared board keeps the list in one place. Add fenbs as a remote server under mcp with the URL https://fenbs.ai/api/mcp, run opencode mcp auth fenbs, sign in and tick what it may do. OpenCode can then read the task it was given, move it to In Progress, comment what changed and move it to Completed, and fenbs records every change in History under the assistant’s name, on your behalf. Change the model next week and the tasks stay exactly where they were.