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.
- Source repo
- wesammustafa/opencode-primer
- Stars
- ★ 403
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 71/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- Typical use
- A developer new to OpenCode who wants a guided ~15-minute path through install, authentication, and a first prompt
- Not a fit if
- Developers who need Copilot-style inline editor completion
- Anyone working over slow SSH or minimal terminals
- Teams that want zero API-key management out of the box
- Source review
- 71/100 · Some gaps
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.json 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/
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.json and manage them with opencode mcp add | list | auth.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenCode Primer This agent | 71 · Some gaps | CLIFree + model costs | ★ 403 | 3mo ago | JavaScript | — |
| CC Workflow Studio | 50 · Major gaps | IDE extensionFree + model costs | ★ 5.4k | 2mo ago | TypeScript | ChatGPT · Codex · Claude Code |
| OSpec | 50 · Major gaps | CLIFree + model costs | ★ 391 | 1mo ago | JavaScript | Codex · Claude Code |
| Claudexor | 76 · Good | CLIFree + model costs | ★ 518 | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
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.