Model or dataset
wesammustafa/opencode-primer avatar
wesammustafa/opencode-primer

opencode-primer: a community guide that names its own gaps

Master OpenCode, the open-source AI coding agent — setup, agents, skills, plugins, MCP, Zen & headless CI.

414 stars27 forksJavaScriptMIT

At a glance

What is it?
A documentation project for the OpenCode coding agent, written by someone who is not on the OpenCode team. Its most useful section is the one listing eight cases where OpenCode is the wrong tool, and its repository configures OpenCode itself, which makes it a readable worked example as well as a reference.
Who is it for?
opencode-primer fits a developer picking between coding agents who wants the trade-offs written down by someone outside the vendor, and it does not fit anyone treating a community guide as canonical, which the README itself warns against. Before following it, check the version it describes against the current binary, because the guide says plainly that documentation trails shipping.
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 133 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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • wesammustafa/opencode-primer414 ★ · +21
Star history
Repository2026-09-122026-11-15
wesammustafa/opencode-primer393414

21 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The section on when to use something else

The guide's most valuable page is the one about when OpenCode is the wrong tool, and it lists eight limitations rather than glossing them.

There is no inline editor completion, because OpenCode is a conversational agent rather than Copilot-style autocomplete; the alternatives named are Copilot, Cursor Tab, Windsurf, which was formerly Codeium, and Supermaven. Output quality depends on the underlying model, so a task that fails on one model is not fixed by moving agents, and provider-agnostic does not mean provider-equivalent because some models tool-call better than others.

The TUI uses truecolor and complex layouts, so it degrades over a slow SSH connection, where a served instance plus attach, or a one-shot run, is the better route. Plugins run arbitrary code with full user permissions and are worth auditing. Free Zen models are described by the Zen documentation as available for a limited time, which the guide turns into a warning against building production on them. And the documentation itself, this guide included, occasionally trails the binary.

Three surfaces, three commands

OpenCode is presented as three interfaces rather than one app. The TUI is the default and starts with the bare command in the current repository. The headless path is a run subcommand taking a prompt, meant for scripts, CI jobs and one-shot work. The third is a server, started with a serve or web command, for a headless API, a web interface or a remote attach.

bash
opencode                                       # start TUI in the current repo
opencode run "fix the failing test in src/api.test.ts"
opencode serve --port 4096                     # headless server

The choice between them is not cosmetic. The run form is what a CI job calls, and the server form is what makes an attach from another machine possible, which is also the answer to the guide's own complaint about the TUI over a slow connection.

It describes the agent as reading the repository rather than working from pasted snippets, using built-in read, grep and glob tools, editing in place with diff-aware edit, write and apply_patch operations, then invoking bash to run tests, linters or builds on the spot.

Install paths, and one curl from a domain

The install section is a list of package managers rather than one blessed path. The primary command pipes a script from the project's own domain:

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

The alternatives are given for whatever you already use: the npm package installed globally, a Homebrew tap, Scoop and Chocolatey on Windows, pacman on Arch, paru for the AUR, and mise. That breadth is the point, and it is also the reason to read before running, since the first option executes a remote script directly.

The guide is explicit about what it is and is not. It is community-maintained and not affiliated with the OpenCode team, and it names the canonical sources as the project's documentation site and the project's own repository, recommending those over itself when the two disagree.

The deeper chapters it points to are custom commands, agent skills, plugins, MCP servers, agents, and headless and CI usage, with models and providers configuration on the side.

The repository configures OpenCode to document OpenCode

The tree is the argument for taking the guide seriously as a worked example. It contains an OpenCode configuration file, a TUI configuration file, an .opencode/ directory, a specialized-agents/ directory and an mcp-servers/ directory, which means the documentation is written inside the tool it documents, with agents and MCP servers configured for the job.

The rest of the repository is documentation hygiene: docs/, an AGENTS.md, CONTRIBUTING.md, a code of conduct, a security policy, an .editorconfig, a Markdown lint configuration with a matching ignore file, and an Images/ directory.

There is one detail that tells you how the guide is maintained. A block of HTML anchors exists purely to keep old internal links alive, mapping generated heading anchors such as setup, agents, plugins, custom-commands, agent-skills, mcp-servers and headless-ci onto stable identifiers including opencode-setup, configuring-providers, prompt-engineering-deep-dive, tui-mastery, subagents, custom-agents and model-context-protocol-mcp.

That is what happens when a documentation site outlives several renames of the thing it describes, and it is a useful thing to copy for any guide that will still be linked next year.

Competitive context, stated in one paragraph

The guide places OpenCode among Claude Code, the Codex CLI and Cursor, and refuses to declare a winner: same problem, different trade-offs, and the choice comes down to which model, surface and ecosystem fit your workflow.

It also dates the field. Gemini CLI was retired in June in favour of a closed-source successor, and Roo Code shut down in May, both in 2026. Two projects disappearing inside one quarter is the context that makes an open-source agent look like a safe default, and the guide puts that in writing rather than leaving it implied.

Its own summary of the trade-off is flexibility and openness over polish and single-vendor integration, worth it for many use cases and not all.

The routing list that follows is the actionable part: a polished single-vendor product points to Claude Code or Codex CLI, a VS-embedded workflow points to Cursor or GitHub Copilot, a small Python tool you can read end to end points to Aider with the note that its development has slowed markedly in 2026, and not wanting to manage provider keys points to a managed hosted product.

A caveat section that reads like a review

Before it explains anything, the guide states the limits of the category: every coding agent can produce wrong code, miss edge cases, hallucinate APIs and over-apply patterns, and the reader remains the reviewer.

The instructions that follow are specific rather than ceremonial. Read diffs before accepting them, run the tests, and do not auto-approve destructive operations on code you care about. One limitation entry expands on the same point from the other direction, saying that diff-aware edits plus passing tests do not guarantee correct, secure or maintainable code, and that AI output should be treated like a junior teammate's pull request.

That framing is worth noting because the rest of the guide is enthusiastic. A community guide that spends its earliest pages on failure modes is making a different argument from one that lists features, and the reader can calibrate accordingly.

It is also why the reading path starts at what OpenCode cannot do rather than at what it added.

Read as documentation, dated like a release

Two dates bracket what this guide is worth. The subject's own claims in the primer are stated as of July 2026, including its position as the most-starred coding agent on GitHub and a monthly user count attributed to the founder. The repository's own last push to main is dated 2026-07-05, and there are no GitHub releases, so nothing in the repository itself is versioned.

That combination is the risk to plan around. A guide with no releases cannot be pinned to the tool version it describes, and the guide says twice that both it and the official documentation trail the binary.

What you can do about it is cheap. The guide organises itself into paths by reader, roughly fifteen minutes for someone new, about twenty minutes each for custom commands, skills, plugins and MCP servers for someone already using it, and a separate route for configuration and headless work, so you can read the chapter that matches your situation and skip the rest.

It is MIT licensed, with a LICENSE file at the root, and it is not affiliated with the project it documents.

Editorial conclusion

opencode-primer fits a developer picking between coding agents who wants the trade-offs written down by someone outside the vendor, and it does not fit anyone treating a community guide as canonical, which the README itself warns against. Before following it, check the version it describes against the current binary, because the guide says plainly that documentation trails shipping. Read the not-the-right-tool section first and decide from that.

Frequently asked questions

Can OpenCode use ChatGPT models?

OpenCode is described as talking to any LLM you point it at, with multi-provider model support, so the guide's stance is that provider choice is open. It also warns that provider-agnostic does not mean provider-equivalent, because some models tool-call better than others, and that output quality depends on the underlying model.

What is the best setup for OpenCode according to opencode-primer?

The guide lists several installers rather than one: piping the install script from the project's domain, the npm package installed globally, a Homebrew tap, Scoop and Chocolatey on Windows, pacman or paru on Arch, and mise. It also separates the choice of interface: a TUI for interactive work, a run subcommand for scripts and CI, and a serve or web command for a headless API or remote attach.

Which provider is best for OpenCode?

The primer does not name one. It states that quality depends on the underlying model and that switching agents will not fix a task that fails on a given model, and that being provider-agnostic is not the same as being provider-equivalent since some models tool-call better than others. It routes readers who do not want to manage provider keys to a managed hosted product instead.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. wesammustafa/opencode-primer on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/wesammustafa-opencode-primer.svg)](https://hysenlabs.com/projects/wesammustafa-opencode-primer)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/wesammustafa-opencode-primer.svg)](https://hysenlabs.com/projects/wesammustafa-opencode-primer)

Was this useful?