opencode-primer: A Community Guide to the OpenCode Coding Agent
Master OpenCode, the open-source AI coding agent — setup, agents, skills, plugins, MCP, Zen & headless CI.
At a glance
- What is it?
- This repository is documentation, not software: a curated guide to installing and configuring OpenCode, covering agents, skills, plugins, MCP servers, and headless CI use. It is useful if you want a single walkthrough of OpenCode's extension surfaces, but it is community-maintained, version-pinned to a moving target, and not a substitute for the official docs.
- Who is it for?
- Adopt this primer if you are starting with OpenCode and want one place that walks from the install command through custom commands, skills, plugins, and MCP configuration, or if you are wiring OpenCode into CI and need the headless surfaces explained together. Skip it if you need inline editor completion (it is a conversational agent, not autocomplete) or a single-vendor product with support.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 73 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What opencode-primer actually is, and who it is written for
The repository is a guide, not a tool. It contains no agent runtime. Its subject is OpenCode, an MIT-licensed AI coding agent maintained by Anomaly that the README describes as a terminal app, desktop app, and IDE extension which reads your repository, runs commands, edits files, and talks to any LLM you point it at. The primer's job is to explain that agent's setup, extension points, and headless surfaces. The README states the audience directly: developers using or about to use OpenCode, with a guided path for beginners and depth on Custom Commands, Skills, Plugins, MCP, and Agents for power users. It also carries an explicit disclaimer that it is not affiliated with the OpenCode team and points to opencode.ai/docs and github.com/anomalyco/opencode as canonical sources. That disclaimer matters more than the usual boilerplate. It means every command in the guide is a second-hand description of another project's interface, and the guide's accuracy is bounded by how closely its authors track upstream releases.
The problem it solves: OpenCode has many surfaces and no single mental model
OpenCode exposes three interfaces, and the primer's value comes from naming them together. The TUI is the default, started with the bare opencode command for interactive work. The CLI and headless path is opencode run "<prompt>", intended for scripts, CI jobs, and one-shot prompts. The server path is opencode serve or opencode web, for a headless API, a web UI, or remote attach. On top of those surfaces sit configuration layers: custom slash commands, agent skills, JS/TS plugins, MCP servers, LSP integration, and formatters. A new user has to work out which surface applies to which task and which configuration file governs it. The primer's contribution is a routing table: a Choose your path section that maps user type to starting sections and rough time estimates, around fifteen minutes for the beginner path and roughly twenty minutes per topic for the extension surfaces. That is documentation work, and it is the kind that official reference material often leaves implicit because the maintainers already know the shape of their own product.
How the guide is organised, and what that reveals about its maintenance
The repository is structured as a single long README with anchor-linked sections rather than a docs site. It includes a block of compatibility anchors with a comment stating they exist for old internal links, covering headings such as setup, agents, plugins, custom-commands, agent-skills, mcp-servers, and headless-ci. That detail is informative: the guide has been re-headed at least once, and the authors added anchors so previously published links would not break. The README also carries a last reviewed badge dated July 2026 and a version badge pinned to OpenCode v1.17.13, and it links an Updates and deprecations section. A guide about a fast-moving agent has a shelf life, and this one at least declares its own expiry. The honest reading is that the version badge is the single most important element on the page. If the badge and your installed OpenCode release diverge, treat the configuration examples as historical until you check them.
Getting OpenCode running, according to the primer
The install instruction the README gives is a single shell pipeline: curl -fsSL https://opencode.ai/install | bash. From there the three surfaces appear as concrete commands. Running opencode with no arguments starts the TUI in the current repository. opencode run "fix the failing test in src/api.test.ts" is the headless form, and the example shows the prompt carrying a file path so the agent has a target. opencode serve --port 4096 starts the server on an explicit port. The README does not reproduce a full configuration file in the excerpt available here, so the exact keys for custom commands, skills, plugins, and MCP entries cannot be confirmed from this material. That is a real gap for a configuration-heavy guide, and the right response is to read the corresponding section on the repository itself and verify each key against opencode.ai/docs before pasting it into a config. Treat the primer as the map and the official docs as the source of truth for syntax.
Where the guide is candid about OpenCode's limits
The strongest part of the README is a section titled When OpenCode isn't the right tool, and it does not hedge. It states plainly that OpenCode offers no inline editor completion: it is a conversational agent, not Copilot-style autocomplete, and it names Copilot, Cursor Tab, Windsurf, and Supermaven as the tools for ghost-text-while-you-type, noting they can be used alongside. It warns that quality depends on the underlying model, so if a task fails on Sonnet, switching to OpenCode will not fix it. It notes that provider-agnostic does not mean provider-equivalent, because some models tool-call better than others and a slug swap is not free. It flags that plugins run arbitrary code with full user permissions and must be audited before installing, and that free Zen models are described in the Zen docs as available for a limited time, so production should not depend on them. It also concedes that the docs lag shipping, meaning the guide and even the official documentation occasionally trail the actual binary. For a community guide, publishing a limitations table that undercuts its own subject is the correct editorial choice.
Alternatives, and the actual difference in approach
The README positions OpenCode against Claude Code, Codex CLI, and Cursor, and its own summary of the trade-off is flexibility and openness over polish and single-vendor integration. The alternatives it names differ in kind, not just in branding. Aider is described as a small Python tool you can read end-to-end, which is a different proposition from a multi-surface agent with plugins and an HTTP server; the README also notes that Aider's development has slowed markedly in 2026, so choosing it is choosing a quieter codebase. Cursor and GitHub Copilot are recommended for people deeply embedded in a VS Code workflow, which is the inline-completion and editor-integration axis OpenCode deliberately does not occupy. Claude Code and Codex CLI are the picks for a polished single-vendor product. The README also records consolidation in the field: Gemini CLI was retired in June in favor of the closed-source Antigravity CLI, and Roo Code shut down in May. That context is worth having, because it means the comparison set is shrinking and the open-source option is becoming less common, not more.
Licence, upkeep, and what the guide costs you to follow
The repository is MIT-licensed, which permits reuse and adaptation of the text with attribution, but it grants nothing with respect to OpenCode itself or the models you connect. Those are separate licences and separate terms, and the guide's own warning about time-limited free Zen models is a reminder that the cost of running an agent sits in model access, not in the documentation. On maintenance: the primer is community-maintained and accepts pull requests, has no releases, and pins itself to a specific OpenCode version with a dated review. There is no stated update cadence in the material available. The practical cost of following it is verification time. Every configuration key, plugin API detail, and MCP server entry should be checked against the current OpenCode release before you commit it to a shared config, because the guide itself says the docs trail the binary. Budget that check as part of reading, not as a later cleanup.
Editorial conclusion
Adopt this primer if you are starting with OpenCode and want one place that walks from the install command through custom commands, skills, plugins, and MCP configuration, or if you are wiring OpenCode into CI and need the headless surfaces explained together. Skip it if you need inline editor completion (it is a conversational agent, not autocomplete) or a single-vendor product with support. Before relying on any page, check the pinned version badge against the current OpenCode release and confirm each config key against opencode.ai/docs, because the repository itself warns that both it and the official docs trail the binary.
Community notes