OpenCode Primer: a community guide to setup, agents, skills and MCP

What OpenCode Primer actually is, and who it is written for

This repository is a guide. It contains no agent runtime, no CLI and no library you import. The README describes it as "everything you need to know about OpenCode", a community-maintained document that is explicitly not affiliated with the OpenCode team. It points readers to opencode.ai/docs and github.com/anomalyco/opencode as the canonical sources.

The subject it documents, OpenCode, is a terminal application, a desktop app and an IDE extension that reads a repository, runs commands, edits files and talks to an LLM you choose. The primer is aimed at two groups. Beginners get a guided path: what OpenCode is, then setup, then prompt engineering, about fifteen minutes of reading by the repository's own estimate. People already using the agent get depth on custom commands, agent skills, plugins and MCP servers, roughly twenty minutes per topic.

The distinction matters when you decide whether to clone it. If you want to run a coding agent, this repository is not the thing you install. If you want to configure one and cannot tell the difference between a custom command, a skill and a plugin, that is the gap it fills. The README also carries a caveat that applies to every coding agent: it can produce wrong code, miss edge cases, hallucinate APIs and over-apply patterns, and the reader is still the reviewer.

How the guide is organised, and the surfaces it separates

The repository layout tells you the structure before you read a word. Alongside README.md and LICENSE there are docs/, mcp-servers/, specialized-agents/, an opencode.json, a tui.json, an AGENTS.md and a .opencode/ directory. So the prose lives in docs/, while worked examples of MCP server definitions and specialised agents sit in their own top-level folders as files you can copy.

The README's path table sorts readers by intent rather than by feature. New users go what-is-it, setup, prompt engineering. Existing users jump straight to custom commands, skills, plugins or MCP. A third row covers configuration and headless use: agents, headless CI, and models and providers. That is a deliberate split between learning the agent and operating it.

The guide also separates OpenCode's three interfaces, which is the mental model most newcomers lack. The TUI is the default surface, started with the bare command. The CLI and headless mode run a one-shot prompt. The server mode exposes a headless API or web UI. Each has a documented command and a documented situation where it fits, and the README notes that the TUI degrades over slow SSH connections, where the server or headless modes are the better choice. That single table saves a reader from discovering the constraint by experience.

Installing OpenCode and running a first prompt

The primer does not ship an installer. It documents OpenCode's own install command, which fetches and runs a shell script from opencode.ai. Run it in your shell:

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

Because that pipes a remote script into bash, read the script before you run it if the machine matters to you. The README gives no Windows-specific instructions, so treat this as the Unix path.

Once the binary is on your PATH, start the interactive TUI inside the repository you want the agent to work on:

opencode

For a one-shot task without the interface, the README gives this example, which asks the agent to fix a failing test file:

opencode run "fix the failing test in src/api.test.ts"

For a headless server on a fixed port, the documented command is:

opencode serve --port 4096

The primer's own configuration files are worth opening after that first run. opencode.json and tui.json at the repository root show the shape of a real configuration, and the .opencode/ directory shows what a project-level setup looks like in a repository that uses the agent daily. Copying those into your own project is faster than reading prose about them.

Where OpenCode Primer says OpenCode is the wrong tool

The guide keeps a table titled "When OpenCode isn't the right tool", and it is the most useful page in the repository because it argues against adoption as readily as for it.

The first entry is inline completion. OpenCode is a conversational agent, not Copilot-style autocomplete. If you want ghost text while you type, the README points at Copilot, Cursor Tab, Windsurf or Supermaven, and suggests running them alongside rather than instead. The second entry is model quality. OpenCode does not replace the underlying model's reasoning, so a task that fails on one model will not be fixed by changing the agent. The third is that provider-agnostic does not mean provider-equivalent: some models tool-call better than others, and swapping a model slug is not free.

The remaining entries are operational. The TUI uses truecolor and complex layouts and degrades over slow connections. Plugins, local or from npm, run with full user permissions, so the README tells you to audit before installing. Free Zen models are described in the Zen docs as available for a limited time, and the primer says not to build production on them. Documentation lags shipping, in the official docs and in this guide alike. And diff-aware edits plus passing tests still do not guarantee correct, secure or maintainable code.

Claude Code, Cursor and Aider: what changes if you switch

The primer places OpenCode next to Claude Code, Codex CLI and Cursor and states plainly that none is universally better. Its guidance is to pick the one whose model, surface and ecosystem fit your workflow. That is a fair framing, but the alternatives differ in kind rather than degree.

Claude Code and Codex CLI are single-vendor products: you get one model family and a polished experience around it. OpenCode's trade-off, in the README's own words, is flexibility and openness over polish and single-vendor integration. The practical consequence is that you manage provider keys yourself. If you would rather not, the guide suggests a managed hosted product or OpenCode Go, its own hosted option.

Cursor and GitHub Copilot are the right answer if your work is embedded in VS Code, because they live in the editor rather than beside it. Aider is the other open-source comparison, and the primer notes that its development has slowed markedly in 2026, which changes the maintenance calculus for anyone choosing an open-source agent today. The README also records that Gemini CLI was retired in June in favour of the closed-source Antigravity CLI, and that Roo Code shut down in May. The field around this guide moved a lot during 2026, and the guide says so.

Maintenance, licensing and what to verify before trusting a page

The repository is MIT-licensed, which permits reuse and modification with attribution and without warranty. The primer's own text is not legal advice and neither is this: if you redistribute the guide or its examples inside a product, read the LICENSE file rather than a summary of it.

The last push to the default branch was on 2026-07-05. That is roughly two and a half months before the date of this article, so the repository is not abandoned, but it is also not receiving daily commits. The README badges its content as last reviewed in July 2026 and pinned to OpenCode v1.17.13, and the guide states that OpenCode moves fast and that it, like the official docs, occasionally trails the actual binary.

That combination is the upgrade cost you are accepting. There are no retrieved releases for this repository, so there is no versioned changelog to diff against. The README does carry an updates and deprecations anchor, which is where review notes are meant to accumulate, and the badge is the only signal of currency. If you copy a configuration snippet from opencode.json or from the mcp-servers/ directory, compare it against the OpenCode release you are running before you commit it to a shared repository.

Editorial conclusion

Adopt OpenCode Primer if you are learning OpenCode or wiring it into a repository and want the configuration surfaces explained in one place. Skip it if you already know the tool, since it will not teach you anything the official docs do not. Before you rely on it, check the badge in the README against the OpenCode release you actually run, because the guide pins itself to v1.17.13 and states that both it and the official docs occasionally trail the binary.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. wesammustafa/opencode-primer on GitHub