OpenCode Primer
A community-maintained, version-verified guide to OpenCode, the open-source AI coding agent — covering setup, agents, skills, plugins, MCP, and headless CI.
Documentation-only product; SECURITY.md declares no runtime dependencies and no build step, example plugins use only Node built-ins; the CI workflow is scoped to contents:read (least privilege). README warns that plugins run arbitrary code, about session-sharing privacy, and not to auto-approve destructive operations. Deductions: actual plugin sources were not included in the evidence, so the claimed secret-blocker behavior cannot be statically verified; the repo itself offers no rollback mechanism — undo/redo merely describes upstream tool behavior.
README claims facts 'verified against the current release', carries version and 'last reviewed' badges, and CI runs markdownlint plus link checking, supporting consistency. Deduction: README is truncated mid-file and many referenced docs (docs/*.md) are absent from evidence, so full internal consistency cannot be confirmed.
Clear reader-path table for beginners and power users; an explicit 'When OpenCode isn't the right tool' table delineates capability boundaries (not autocomplete, model-dependent quality, TUI degradation on slow SSH, plugin risk, time-limited free models) — rare candor for this genre. Deductions: trigger precision and environment fit mostly restate upstream tool behavior rather than this repo's own design.
Strong information architecture: path-selection table, mermaid decision flowchart, five-extension comparison, compatibility anchors. Full MIT LICENSE matching the badge; thorough known-limitations table. Deductions: no CHANGELOG file (only badge dates and an anchor); the actual example files (agents/commands/plugins/skills) are referenced but absent from evidence, so examples_and_faq earns only a mid score; single community maintainer with no CODEOWNERS or governance statement.
Output is immediately copy-pasteable: install commands, config snippets, command/skill/plugin templates, structured tables. Deductions: as a third-party community guide its marginal value depends on upstream docs lag, which the README itself admits ('docs lag shipping'); cost_benefit for a pure docs product can only be moderate.
Claims generally carry source links and verification dates (pricing snapshot 'verified 2026-07-05', PR #18186, third-party press). Facts and opinions are largely separated via quoted warnings and recommendations. Deductions: static review cannot independently corroborate 'most-starred', '8M monthly users', or the 2026 pricing; no in-repo test or comparison evidence exists, so cross_source_corroboration scores 1.
- This repo is a documentation guide only; example plugin sources were not included in the evidence, so claims like the secret blocker are unverified — read the actual files under .opencode/plugins/ before copying them.
- 2026-era pricing, user counts, and competitor claims in the README cannot be cross-verified statically; check opencode.ai official docs before relying on them.
- The guide itself admits it lags upstream releases; the install command (curl | bash) is third-party relayed — verify against the official source before running.
- Publisher is an unverified individual with no governance or accountability statement; treat factual security guidance with independent judgment.
What does this agent do, and when should you use it?
OpenCode Primer (GitHub: wesammustafa/opencode-primer) is an MIT-licensed developer tutorial repository for OpenCode, with every fact verified against release v1.17.13. It is not OpenCode itself but a manual covering installation, authentication, model access (direct providers, the Zen pay-as-you-go gateway, the Go subscription, local models), prompt engineering, TUI keybinds and themes, headless CLI usage, and CI integration. The repository ships a working .opencode/ example directory with custom agents, slash commands, JS plugins (protect-secrets.js and audit-log.js), a SKILL.md skill, and an AGENTS.md project rules file. Deep dives live in topic files under docs/ (agents.md, plugins.md, mcp.md, zen.md, and more), supplemented by an FAQ, a Claude Code migration guide, and a changelog. Readers should treat it as a learning and configuration reference, not a deployable software product.
The repository delivers three kinds of content. First, tutorial documentation: OpenCode installation (curl script, npm, brew, scoop, Docker, and more), opencode auth login, /init for generating AGENTS.md, the plan/build agent workflow toggled with Tab, @file and !shell prompt syntax, leader-key bindings and themes, headless modes (opencode run / serve / web), and CI integration via opencode github install. Second, runnable configuration examples: .opencode/agents/ (markdown+YAML agent definitions), .opencode/commands/ (four commands: /review, /pr, /test, /optimize), .opencode/plugins/ (an audit-log and a secret-protection plugin), .opencode/skills/git-release/ (a SKILL.md), and opencode. with sample MCP server config. Third, reference assets: specialized-agents/ with copy-paste specialist prompts (backend, frontend, code reviewer, security reviewer, tech lead, database, UX), and mcp-servers/ walkthroughs for Playwright, Context7, Sentry, and Grep.
- A developer new to OpenCode who wants a guided ~15-minute path through install, authentication, and a first prompt
- A team migrating from Claude Code that needs the AGENTS.md/CLAUDE.md fallback rules, path differences, and frontmatter key changes
- A cost-conscious user choosing between direct providers, Zen per-token pricing, the $10/month Go plan, and local models, using the documented price snapshot and the cheap-explorer/strong-executor pattern
- An engineer adding guardrails to AI sessions who can directly reuse the protect-secrets.js and audit-log.js plugins
- A DevOps engineer building unattended pipelines following the Headless & CI recipes for opencode run --format , GitHub Actions, or GitLab CI
- A developer wiring up external tools via MCP using the Playwright, Context7, Sentry, and Grep walkthroughs in mcp-servers/
What are this agent's strengths and limitations?
- Content is verified against a specific release (v1.17.13) with a stamped last-reviewed date, reducing tutorial-rot risk
- The bundled .opencode/ directory provides directly copyable assets: security and audit plugins, four slash commands, and a git-release skill
- End-to-end coverage: install, model selection (including a Zen price snapshot), prompt engineering, headless CI, and MCP integration in one guide
- Clearly discloses its community-maintained, non-affiliated status and consistently links official docs as the source of truth
- It is documentation, not software — it cannot substitute for OpenCode itself, and actual behavior depends on the separately installed and paid-for tool and its underlying models
- The guide admits it can lag the fast-moving binary; prices and features (e.g., Zen pricing snapshot dated 2026-07-05) may already have changed
- Some guidance is ecosystem-bound: Claude Pro/Max subscription login no longer works, plugins require JS/TS and Bun, and free Zen models are time-limited and flagged as unfit for production
- Examples follow OpenCode conventions (AGENTS.md, .opencode/ layout) and are not directly portable to other coding agents
How do you install or deploy this agent?
This is a documentation repository — no runtime to install. Get it with: git clone https://github.com/wesammustafa/opencode-primer.git, or read it on GitHub. To actually run its examples you must first install OpenCode: curl -fsSL https://opencode.ai/install | bash (or npm i -g opencode-ai@latest / brew install anomalyco/tap/opencode), then run opencode auth login to authenticate at least one LLM provider — a prerequisite the repository itself does not fulfill.
How do you use this agent?
Follow the 'Choose your path' table in the README: beginners start with What is OpenCode → Setup → Prompt Engineering; existing users jump to Custom Commands, Agent Skills, Plugins, or MCP (~20 min each); configuration and CI needs point to Agents, Headless & CI, and Models & Providers. Deep dives live in docs/ (e.g., docs/agents.md, docs/plugins.md, docs/workflows.md, docs/reference/cli.md). To try the examples, copy the repository's .opencode/agents/*.md, .opencode/commands/*.md, and .opencode/skills/ into your project's matching directories, or drop a specialist prompt from specialized-agents/ into .opencode/agents/<name>.md. Configure MCP servers in the mcp section of opencode. and manage them with opencode mcp add | list | auth.
How does this agent compare with similar options?
The README positions OpenCode itself against Claude Code, Codex CLI, Cursor, and Aider (e.g., choose Claude Code/Codex CLI for a polished single-vendor product, Cursor/Copilot for a deep VS Code workflow, Aider for a small readable Python tool), noting OpenCode trades polish for openness and provider flexibility. For this guide, the nearest alternative is the official documentation at opencode.ai/docs.