- 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 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.
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.