- H1 and banner now lead with 'OpenCode Primer' (old title kept as tagline)
- All absolute repo URLs updated to wesammustafa/opencode-primer
(GitHub redirects the old slug, but canonical links are cleaner)
- Social preview re-rendered from the updated banner
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.
Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
with an (input, output) signature, not event.type values. Rewrite both
shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
"*" first), not most-specific-wins. Fix prose, reorder examples, and fix
the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
into model options; fix the `mise` install command.
Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
native GitHub commands; correct the specialist-prompt count; bump dates.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The 'one_or_ordered' setting didn't fix the issue — markdownlint
breaks numbered lists into separate lists wherever there's intervening
non-list content (code fences, paragraphs, shell prompts), and then
flags the second list's first item as a continuation that should have
been numbered 1.
Our command/skill markdown files intentionally interleave numbered
steps with non-list content (shell prompts the agent executes,
explanations). The lint is fighting an editing pattern, not catching
a real readability bug.
markdownlint
- Disable MD028 (no-blanks-blockquote): we intentionally separate
adjacent blockquote callouts (a tip + a warning side-by-side) with
a blank line; visually this renders as two callouts, which is the
intent.
- Switch MD029 (ol-prefix) to "one_or_ordered": both "1. / 2. / 3."
and "1. / 1. / 1." (auto-renumber) are valid; the rule was hitting
ordered lists that have intervening code blocks, where the lint
loses count.
- Add blank lines before lists in five places where MD032 fired
(test.md, git-release/SKILL.md, agents.md, skills.md, migration.md).
- Fix nested code-fence bug in database-engineer-prompt.md: the
outer ``` was being closed by an inner ```sql; switched the outer
fence to ```` (4 backticks) so the inner one stays nested.
link-check
- Ignore https://mcp.grep.app and https://ai.google.dev/ — the first
returns 405 to HEAD requests (verified working via GET); the second
trips an infinite-redirect bug in the link checker (real URL works).
- Ignore github.com/anomalyco/opencode/discussions — the upstream
repo currently has discussions disabled.
- Add 405 to aliveStatusCodes for endpoints that accept GET but
reject HEAD.
The previous README was 21 flat H3 sections with three competing
H2 navigation blocks at the top. Several pieces sat in unnatural places
and three pairs of sections were artificial splits of the same concept.
This rewrite simplifies the layout:
Hierarchy
- One H2 navigation block at the top: 'Choose your path' (was three).
- Four H2 content groups: Getting started, Using OpenCode, Extending
OpenCode, Reference. Each holds a small number of H3 sections.
- 17 H3 sections total (down from 21). Clearer GitHub TOC.
Reordered for a top-to-bottom narrative
- 'When OpenCode isn't the right tool' moved up to right after
'What is OpenCode?', so trade-offs are visible before sinking time
into Setup.
- TUI & Themes moved from end-of-page into 'Using OpenCode' alongside
Prompt Engineering, where 'how do I drive this?' belongs.
- 'Pick the right extension' (the mermaid decision tree) now opens
'Extending OpenCode' inline, where it has context. Previously it sat
at the top of the page before any extension had been introduced.
Merged artificial splits
- OpenCode Zen + Configuring providers → Models & Providers, with a
3-way comparison up front (direct / Zen / local) and the Zen lineup
as an H4 inside it.
- Subagents + Custom Agents → Agents, with built-in agents first,
custom agents second. They're the same file format with different
'mode:' values; the old split made the reader trace forward refs.
- TUI Mastery + Themes → TUI & Themes.
Trimmed redundancy
- Removed the table that duplicated the mermaid decision tree in
'When to use what'. The mermaid was the unique visual; the table
was repetition.
- Dropped the standalone 'What's inside' index — replaced by the H2
group hierarchy itself.
Compatibility
- Added <a id> compatibility anchors for old internal links
(#opencode-setup, #configuring-providers, #prompt-engineering-deep-dive,
#tui-mastery, #subagents, #custom-agents, #model-context-protocol-mcp,
#when-to-use-what, #whats-inside) so any external bookmarks still land
on the page.
- Anchors for #opencode-zen and #themes are still produced by their
H4 headings inside the merged sections, so existing deep links still
resolve.
Net effect: 893 lines → 708 lines, same factual coverage, clearer flow.
Community and contributor support:
- CONTRIBUTING.md: what we welcome, what we don't, style guide,
templates for MCP walkthroughs and specialized-agent prompts.
- CODE_OF_CONDUCT.md: Contributor Covenant 2.1.
- SECURITY.md: scope (this is a docs repo, not application code), how
to report a vulnerability in the example plugins or in misleading
documentation, where OpenCode-core bugs should go instead.
GitHub plumbing:
- .github/PULL_REQUEST_TEMPLATE.md: type, sources, hygiene checklist.
- .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md and config.yml
that redirects OpenCode-tool issues to the right place.
- .github/workflows/lint-docs.yml: three jobs on every push and PR —
markdownlint, link check (with sensible ignore patterns for
../../issues, security advisories, localhost), codespell with a
project-specific ignore list.
Lint/style configs:
- .markdownlint.json + .markdownlintignore: ATX headings, ordered list
numbering, line-length and inline-HTML rules tuned for our content.
- .editorconfig: LF, UTF-8, 2-space indent, trim trailing whitespace
except in markdown (where trailing spaces are line breaks).
- opencode.json: a real, runnable project config with safe defaults —
edit:"ask", glob-pattern bash map (auto-allow common read-only ops,
deny rm -rf and git push --force), webfetch and websearch on "ask",
external_directory denied. Useful as a starting point readers can
copy verbatim.
- tui.json: minimal example covering theme, scroll speed, leader
timeout, keybinds, attention/notifications.
- Images/README.md: replaces .gitkeep with explicit contribution rules
— no copyrighted material, prefer SVG over PNG, prefer mermaid over
raster when the concept fits.
Each walkthrough follows the same template: when to reach for it, setup
(verbatim opencode.json snippet), example prompts, capabilities and
limitations, gotchas, resources.
- playwright.md: browser automation — visual iteration loop, e2e
scaffolding, bug repro from a URL
- context7.md: live, version-pinned library docs piped into the prompt,
with the "resolve first, query second" pattern
- sentry.md: errors / traces / releases via OAuth (DCR), with the
error-to-root-cause pattern
- grep.md: code search across public GitHub via the Vercel-hosted MCP
README.md ranks "when to add a server" against the cost of the extra
tokens it puts in the model's context every turn, with a tools-map
example for disabling chatty MCP tools per agent.
All endpoint URLs and package names link-checked at commit time.
Ready-to-copy prompts under specialized-agents/system-prompts/:
- code-reviewer-prompt.md (subagent, read-only)
- security-reviewer-prompt.md (subagent, read-only, CWE-aware)
- backend-engineer-prompt.md (primary or all)
- frontend-engineer-prompt.md (primary or all)
- tech-lead-prompt.md (primary, opus-tier)
- database-engineer-prompt.md (Postgres-first, adapts)
- ux-engineer-prompt.md (design-system-first)
Matching one-page descriptions in specialized-agents/descriptions/.
Every prompt opens with a "one defensible set of opinions, not the only
right answer" disclaimer so readers don't treat them as authoritative.
Stack-specific defaults (Tailwind, FastAPI, Postgres) are explicitly
overridable per project.
To install one:
cp specialized-agents/system-prompts/code-reviewer-prompt.md \
.opencode/agents/code-reviewer.md
or reference via {file:...} from opencode.json without copying.
This repo doubles as a fully-configured OpenCode project so readers can
see real files instead of abstract format docs.
Agents (.opencode/agents/, OpenCode YAML + markdown body):
- code-reviewer.md — read-only subagent, glob-gated bash perms,
Severity/Where/Why/Fix output format. Rewrites the pre-refactor file
which used incorrect frontmatter shape (no YAML, claude-sonnet-4.6
as bare ID, made-up tool keys).
- security-auditor.md — OWASP-focused review subagent, deny edit,
ask bash, CWE-aware output template.
Commands (.opencode/commands/):
- review.md, pr.md, test.md, optimize.md — uses real placeholders
($ARGUMENTS, @file, !shell), points the right agent at each task.
Plugins (.opencode/plugins/):
- protect-secrets.js — blocks tool calls touching .env*, secrets/,
credentials*, SSH keys, .npmrc, .pypirc. Pure JS, no deps.
- audit-log.js — appends one JSON line per successful tool call to
.opencode/audit.jsonl (also added to .gitignore).
- README.md — how to install/disable, sample audit-log line, link to
docs/plugins.md.
Skills (.opencode/skills/git-release/SKILL.md):
- Proper folder-with-SKILL.md format. Trigger-shaped description so the
model actually loads it when the conversation touches release prep.
- quickstart.md: 5-minute path from curl to first commit
- zen.md: model gateway with full lineup, pricing, BYOK, patterns
- tui.md: keybinds, leader chords, themes, customization, sessions
- agents.md: custom agents and subagents, full frontmatter, permission map
- commands.md: custom slash commands, placeholders, patterns, override rules
- skills.md: discoverable workflows, SKILL.md format, description-as-trigger
- plugins.md: lifecycle hooks, full event catalog, four real patterns
- mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers,
with mermaid N×M → N+M diagram
- migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does
better" subsections so the comparisons aren't one-sided
- workflows.md: seven real recipes (TDD, bug investigation, multi-agent
review, cross-repo research, migrations, CI, visual iteration) — CI
example shows GitHub Actions + GitLab CI to avoid platform bias
Every model slug, permission key, config key, env var, and CLI flag
verified against the JSON schema or the live docs site.
README
- Match the structure of common practical-guide repos: title, badges,
install one-liner, "Choose your path", "When to use what" decision
tree (mermaid) + table, "What's inside" topical map, deep dives,
Limitations, FAQ, Updates, References.
- Add explicit not-affiliated-with-OpenCode disclaimer per OpenCode's
own README request for third-party projects using "opencode" in the
name.
- Add AI-coding caveat (you're still the reviewer, hallucinations are
real) at the top.
- Add balanced "When OpenCode isn't the right tool" subsection naming
Claude Code, Cursor, Aider, Copilot, Codeium, Supermaven as better
fits for specific use cases.
- All factual claims verified against opencode.ai/docs and the JSON
config schema. Pricing/model table dated 2026-05-18.
AGENTS.md
- Repurpose from generic React boilerplate to actually describe this
repo: a documentation guide. Includes editing rules, style guide,
emoji policy, and "when to update what" matrix.
- Delete eight pre-refactor doc files under docs/ (AGENTS-GUIDE,
COMMANDS-REFERENCE, FAQ-TROUBLESHOOTING, MCP-GUIDE, MIGRATION-GUIDE,
SKILLS-GUIDE, TUI-MASTERY, ZEN-GUIDE). They were inaccurate to current
OpenCode behavior; replacements land in a follow-up commit.
- Remove .opencode/skills/{pr,review}.md — these were placed as files,
but OpenCode skills require folder-with-SKILL.md format. Equivalent
content is being re-shipped as .opencode/commands/ entries.
- Remove Images/opencode.png and opencode-installation.png — these are
OpenCode's own branding assets; not appropriate to redistribute from
a non-affiliated community guide.
- Remove Images/.gitkeep — superseded by Images/README.md in a later commit.
The previous .gitignore excluded .opencode/agents/, /commands/, and /skills/ —
which prevented committing the very example files this repo is meant to
showcase. Keep user-specific runtime state (cache, logs, sessions, audit log,
local state) ignored; un-ignore the example folders.