diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 21b60c6..ddf4002 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -7,5 +7,5 @@ contact_links:
url: https://opencode.ai/docs
about: Official documentation.
- name: OpenCode community Discord
- url: https://discord.gg/opencode
+ url: https://opencode.ai/discord
about: Real-time chat with the OpenCode community.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 3cd9374..b2b697f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -22,9 +22,9 @@ Drive-by claims without sources will get held until they can be verified.
## Checklist
-- [ ] I read [`CONTRIBUTING.md`](../CONTRIBUTING.md)
+- [ ] I read [`CONTRIBUTING.md`](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/blob/main/CONTRIBUTING.md)
- [ ] Every factual claim cites a source (in the PR or inline in the doc)
- [ ] In-page anchors and cross-doc links still resolve
- [ ] No trailing whitespace; code fences have language tags
-- [ ] Emoji follow the [`AGENTS.md` policy](../AGENTS.md#style-conventions) (H2 navigation + callout prefixes only)
+- [ ] Emoji follow the [`AGENTS.md` policy](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/blob/main/AGENTS.md#style-conventions) (H2 navigation + callout prefixes only)
- [ ] If I touched the README, I updated the "Last reviewed" line at the bottom
diff --git a/.markdownlint.json b/.markdownlint.json
index 38d0551..200dc10 100644
--- a/.markdownlint.json
+++ b/.markdownlint.json
@@ -8,6 +8,7 @@
"MD026": { "punctuation": ".,;:" },
"MD028": false,
"MD029": false,
+ "MD060": false,
"MD033": false,
"MD036": false,
"MD040": false,
diff --git a/.opencode/agents/code-reviewer.md b/.opencode/agents/code-reviewer.md
index 3066441..58afbec 100644
--- a/.opencode/agents/code-reviewer.md
+++ b/.opencode/agents/code-reviewer.md
@@ -1,7 +1,7 @@
---
description: Senior code reviewer — reads diffs and surfaces bugs, security issues, and maintainability problems without modifying files.
mode: subagent
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.1
permission:
edit: deny
diff --git a/.opencode/agents/security-auditor.md b/.opencode/agents/security-auditor.md
index a345bfb..3cde73a 100644
--- a/.opencode/agents/security-auditor.md
+++ b/.opencode/agents/security-auditor.md
@@ -1,7 +1,7 @@
---
description: Security-focused reviewer — audits code for vulnerabilities (OWASP Top 10, secret leaks, auth/authz issues) and reports findings without modifying files.
mode: subagent
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.1
permission:
edit: deny
diff --git a/.opencode/commands/pr.md b/.opencode/commands/pr.md
index aa5f360..e4b4a1c 100644
--- a/.opencode/commands/pr.md
+++ b/.opencode/commands/pr.md
@@ -7,9 +7,9 @@ Create a pull request from the current branch:
1. Read the current state:
-!git status --short
-!git log main..HEAD --oneline
-!git diff main...HEAD --stat
+!`git status --short`
+!`git log main..HEAD --oneline`
+!`git diff main...HEAD --stat`
2. Decide on a PR title:
- Match the repo's conventional-commits style (`feat:`, `fix:`, `refactor:`, `docs:`, …)
diff --git a/.opencode/commands/review.md b/.opencode/commands/review.md
index 0fb4dcc..efdb2bf 100644
--- a/.opencode/commands/review.md
+++ b/.opencode/commands/review.md
@@ -8,7 +8,7 @@ Run a code review with these inputs:
- Scope: `$ARGUMENTS` if provided, otherwise the current branch's diff vs `main`.
- Changed files (always check):
-!git diff --name-only main...HEAD
+!`git diff --name-only main...HEAD`
For each changed file, evaluate (in this order):
diff --git a/.opencode/commands/test.md b/.opencode/commands/test.md
index eee9959..e57b13f 100644
--- a/.opencode/commands/test.md
+++ b/.opencode/commands/test.md
@@ -7,7 +7,7 @@ Run the project test suite and triage failures.
1. Detect the runner from the repo and run it:
-!cat package.json 2>/dev/null | grep -E '"test"|"scripts"' | head -5
+!`cat package.json 2>/dev/null | grep -E '"test"|"scripts"' | head -5`
Pick the right command:
@@ -17,9 +17,7 @@ Pick the right command:
- `cargo test` for Rust
- Other: read the project's `AGENTS.md` for the canonical command
-2. Run it and capture the output:
-
-!{the chosen test command}
+2. Run the chosen test command with the bash tool and capture the output. (Shell injections like the one above expand *before* the model runs, so the command you picked in step 1 has to be run as a normal tool call, not a template.)
3. If everything passes, print a one-line summary and stop.
diff --git a/.opencode/plugins/README.md b/.opencode/plugins/README.md
index fe02690..7061bcc 100644
--- a/.opencode/plugins/README.md
+++ b/.opencode/plugins/README.md
@@ -33,7 +33,7 @@ Sample line:
Three options:
1. Move the plugin file out of `.opencode/plugins/`.
-2. Comment out the `export default` line.
+2. Comment out **all** exports in the file (every export is loaded, so a leftover one keeps the plugin alive) — or rename the file to a non-`.js`/`.ts` extension.
3. Gate the body of the plugin on an env var:
```js
diff --git a/.opencode/plugins/audit-log.js b/.opencode/plugins/audit-log.js
index 2d7c2c2..cf9bb5a 100644
--- a/.opencode/plugins/audit-log.js
+++ b/.opencode/plugins/audit-log.js
@@ -31,5 +31,3 @@ export const AuditLog = async ({ directory }) => {
},
};
};
-
-export default AuditLog;
diff --git a/.opencode/plugins/protect-secrets.js b/.opencode/plugins/protect-secrets.js
index 600b4c3..18f6c92 100644
--- a/.opencode/plugins/protect-secrets.js
+++ b/.opencode/plugins/protect-secrets.js
@@ -5,7 +5,7 @@
// on top of `external_directory: deny` and gitignore — never your only line
// of defense, but a useful one.
-const SENSITIVE = /(^|\/)(\.env(\..*)?|secrets|credentials|id_rsa|id_ed25519|\.npmrc|\.pypirc)(\b|\/)/i;
+const SENSITIVE = /(^|[\s\/"'=])(\.env(\.[^\s]*)?|secrets|credentials|id_rsa|id_ed25519|\.npmrc|\.pypirc)(\b|\/)/i;
// Pull the most likely path/command field out of a tool's arguments.
// `read`/`edit`/`write` use `filePath`; `bash` uses `command`; others vary.
@@ -36,5 +36,3 @@ export const ProtectSecrets = async () => {
},
};
};
-
-export default ProtectSecrets;
diff --git a/AGENTS.md b/AGENTS.md
index 5f383d3..00b6f80 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,9 @@ A practical, opinionated guide to using [OpenCode](https://opencode.ai) — READ
├── README.md # Main guide (the centerpiece)
├── AGENTS.md # This file
├── CONTRIBUTING.md # How to contribute
+├── SECURITY.md · CODE_OF_CONDUCT.md
├── LICENSE # MIT
+├── opencode.json · tui.json # Example configs with safe defaults
├── docs/
│ ├── quickstart.md # 5-minute getting-started
│ ├── zen.md # Zen model gateway details
@@ -25,22 +27,24 @@ A practical, opinionated guide to using [OpenCode](https://opencode.ai) — READ
│ ├── mcp.md # MCP integration
│ ├── workflows.md # Real-world recipes
│ ├── migration.md # Migration from Claude Code / Cursor
-│ ├── faq.md # FAQ + troubleshooting
│ └── reference/
│ ├── cli.md # All CLI commands
│ ├── slash-commands.md # All TUI slash commands
│ ├── permissions.md # Permission model
│ ├── changelog.md # OpenCode releases
+│ ├── faq.md # FAQ + troubleshooting
│ └── further-reading.md # External resources
├── .opencode/
│ ├── agents/ # Example custom agents
│ ├── commands/ # Example custom commands
+│ ├── plugins/ # Example plugins (audit log, secret blocker)
│ └── skills/ # Example agent skills
+├── .github/ # CI (lint-docs.yml), issue/PR templates
├── mcp-servers/ # MCP server walkthroughs
├── specialized-agents/ # Drop-in specialist prompts
-│ ├── system-prompts/ # System prompts (10 roles)
+│ ├── system-prompts/ # System prompts (7 roles)
│ └── descriptions/ # Role descriptions
-└── Images/ # Diagrams and screenshots
+└── Images/ # Banner, diagrams, screenshots
```
## Editing rules
@@ -93,14 +97,17 @@ A practical, opinionated guide to using [OpenCode](https://opencode.ai) — READ
## Commands
-This repo has no build/test stack — it's pure markdown. Useful housekeeping:
+No build step, but CI (`.github/workflows/lint-docs.yml`) lints every push/PR to `main`. Run the same checks locally before committing:
```bash
-# Spell-check (if installed)
-codespell README.md docs/
+# Markdown lint (config: .markdownlint.json)
+npx markdownlint-cli2 "**/*.md"
-# Find broken internal links
-grep -nE '\]\(#[a-z0-9-]+\)' README.md docs/*.md
+# Spell-check (ignore list: .github/codespell-ignore.txt)
+codespell --ignore-words=.github/codespell-ignore.txt --skip="./LICENSE,./.git,./node_modules" .
+
+# Link check (config: .github/markdown-link-check.json)
+npx markdown-link-check -c .github/markdown-link-check.json README.md
```
## How OpenCode should work in this repo
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index ea86417..2a19b71 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -30,7 +30,7 @@ This Code of Conduct applies within all project spaces — issues, pull requests
## Enforcement
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers by opening a confidential issue or contacting the repository owner directly. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers by contacting the repository owner directly via their GitHub profile. (For security issues specifically, use [GitHub's private vulnerability reporting](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/security/advisories/new) instead — see [`SECURITY.md`](SECURITY.md).) All complaints will be reviewed and investigated promptly and fairly.
Maintainers are obligated to respect the privacy and security of the reporter of any incident.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b574014..3629021 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,19 +62,24 @@ A good system prompt has:
Add the matching short description under [`specialized-agents/descriptions/`](specialized-agents/descriptions/) and update the table in [`specialized-agents/README.md`](specialized-agents/README.md).
-## Local check
+## Local checks
-There's no build system to run, but a quick mental checklist before submitting:
+CI (`.github/workflows/lint-docs.yml`) runs markdownlint, a link check, and a spell check on every PR. Run the same checks locally before submitting:
-- [ ] All links resolve (in-page anchors and external URLs)
-- [ ] Code fences have language tags
-- [ ] No trailing whitespace
-- [ ] No emoji clutter
-- [ ] Facts cite a source
+```bash
+# Markdown lint (same rules as CI)
+npx markdownlint-cli2 "**/*.md"
+
+# Spell check (same ignore list as CI)
+codespell --ignore-words .github/codespell-ignore.txt --skip "./LICENSE,./.git,./node_modules"
+
+# Link check (same config as CI) — run per changed file
+npx markdown-link-check -c .github/markdown-link-check.json README.md
+```
## Questions
-Open a [GitHub Discussion](../../discussions) or an [issue](../../issues). Drive-by PRs are welcome too — we'll suggest changes in review.
+Open a [GitHub Discussion](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/discussions) or an [issue](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/issues). Drive-by PRs are welcome too — we'll suggest changes in review.
---
diff --git a/Images/README.md b/Images/README.md
index 161a06e..2c509e7 100644
--- a/Images/README.md
+++ b/Images/README.md
@@ -12,6 +12,8 @@ Diagrams, screenshots, and visual assets for this guide.
```
+ Paths are relative to the *referencing* file — `Images/your-image.svg` works from the root `README.md`, but a doc under `docs/` needs `../Images/your-image.svg`.
+
- **Include alt text.** Always.
- **Mermaid before raster.** When a concept can be expressed as a flowchart or sequence diagram, prefer Mermaid (renders natively on GitHub) over an exported PNG. See [`docs/mcp.md`](../docs/mcp.md) for an example.
diff --git a/Images/banner.svg b/Images/banner.svg
new file mode 100644
index 0000000..18c31fd
--- /dev/null
+++ b/Images/banner.svg
@@ -0,0 +1,74 @@
+
diff --git a/Images/social-preview.png b/Images/social-preview.png
new file mode 100644
index 0000000..fbbd4ff
Binary files /dev/null and b/Images/social-preview.png differ
diff --git a/README.md b/README.md
index ea50e94..a9bd270 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,14 @@
+
+
# OpenCode: Everything You Need to Know
-A practical guide to [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Built around clear mental models and real examples, not marketing.
+The community field guide to [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Clear mental models, real examples, every fact verified against the current release.
[](LICENSE)
-[](https://github.com/anomalyco/opencode/releases)
-[](#updates--deprecations)
+[](https://github.com/anomalyco/opencode/releases)
+[](#updates--deprecations)
[](CONTRIBUTING.md)
+[](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/stargazers)
```bash
curl -fsSL https://opencode.ai/install | bash
@@ -15,6 +18,8 @@ curl -fsSL https://opencode.ai/install | bash
> ⚖️ **Not affiliated with the OpenCode team.** This is a community-maintained guide. For canonical sources, check [opencode.ai/docs](https://opencode.ai/docs/) and [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode).
+> 💡 **Pro Tip:** If this guide saves you an afternoon, a ⭐ helps other developers find it.
+
---
## 🧭 Choose your path
@@ -44,7 +49,7 @@ curl -fsSL https://opencode.ai/install | bash
### What is OpenCode?
-OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by [Anomaly](https://github.com/anomalyco), MIT-licensed.
+OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by [Anomaly](https://github.com/anomalyco), MIT-licensed — and as of July 2026 the [most-starred coding agent on GitHub](https://github.com/anomalyco/opencode) (182K+ stars), with [8M monthly users by the founder's count](https://betakit.com/qa-opencodes-founder-on-how-the-ai-agent-went-from-zero-to-8-million-users-in-a-year/).
**Three things it does that a chat UI can't:**
@@ -66,7 +71,7 @@ opencode run "fix the failing test in src/api.test.ts"
opencode serve --port 4096 # headless server
```
-> OpenCode sits in the same space as Claude Code, Cursor, and Aider — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow.
+> OpenCode sits in the same space as Claude Code, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was [retired in June](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)
> ⚠️ **AI-coding caveat:** OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. **You're still the reviewer.** Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.
@@ -76,7 +81,7 @@ opencode serve --port 4096 # headless server
| Limitation | Detail |
|---|---|
-| **No inline editor completion** | OpenCode is a conversational agent, not Copilot-style autocomplete. For ghost-text-while-you-type, reach for [Copilot](https://github.com/features/copilot), [Cursor Tab](https://cursor.sh/), [Codeium](https://codeium.com/), or [Supermaven](https://supermaven.com/) — or alongside. |
+| **No inline editor completion** | OpenCode is a conversational agent, not Copilot-style autocomplete. For ghost-text-while-you-type, reach for [Copilot](https://github.com/features/copilot), [Cursor Tab](https://cursor.com/), [Windsurf (formerly Codeium)](https://windsurf.com/), or [Supermaven](https://supermaven.com/) — or alongside. |
| **Quality depends on the underlying model** | OpenCode doesn't replace the LLM's reasoning. If your task fails on Sonnet, switching to OpenCode won't fix it. |
| **Provider-agnostic ≠ provider-equivalent** | Some models tool-call better than others. A slug swap isn't free. |
| **TUI on slow SSH / minimal terminals** | The TUI uses truecolor and complex layouts. Degrades over slow connections. `opencode serve` + `attach` or `opencode run` are better for those cases. |
@@ -87,10 +92,10 @@ opencode serve --port 4096 # headless server
**When something else fits better:**
-- Want a polished single-vendor product → **Claude Code** or **Cursor**.
+- Want a polished single-vendor product → **Claude Code** or **Codex CLI**.
- Deeply embedded in VS Code workflow → **Cursor** or **GitHub Copilot**.
-- Want a small Python tool you can read end-to-end → **[Aider](https://aider.chat/)**.
-- Don't want to manage provider keys → a managed hosted product.
+- Want a small Python tool you can read end-to-end → **[Aider](https://aider.chat/)** (note: development has slowed markedly in 2026).
+- Don't want to manage provider keys → a managed hosted product, or [OpenCode Go](#opencode-go).
> OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.
@@ -115,8 +120,8 @@ scoop install opencode # Windows
choco install opencode # Windows
sudo pacman -S opencode # Arch
paru -S opencode-bin # Arch (AUR)
-mise use -g github:anomalyco/opencode # mise users
-nix run nixpkgs#opencode # Nix
+mise use -g github:anomalyco/opencode # mise users
+docker run -it --rm ghcr.io/anomalyco/opencode # Docker
```
A desktop app for macOS / Windows / Linux is in beta at [opencode.ai/download](https://opencode.ai/download).
@@ -170,22 +175,25 @@ This repo's own [`.opencode/`](.opencode/) directory is a working example:
### Models & Providers
-OpenCode is **provider-agnostic**. Three ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:
+OpenCode is **provider-agnostic**. Four ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:
| | Best for | Trade-off |
|---|---|---|
| **Direct providers** (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure) | You already have credits with a provider | Manage one key per provider |
| **[OpenCode Zen](#opencode-zen)** — pay-as-you-go gateway | One key, curated lineup, no commitment | Pricier per token than going direct in some cases |
+| **[OpenCode Go](#opencode-go)** — flat-rate subscription | Predictable $10/month, zero key management | Curated open models only, usage limits |
| **Local models** (Ollama, LM Studio, llama.cpp) | Offline, strict data-residency, hobbyist | Quality varies hugely with model and hardware |
There's no universally right answer — pick what fits.
+> ⚠️ **Warning:** You can no longer sign in with a Claude Pro/Max subscription. OpenCode removed its built-in Anthropic OAuth login in March 2026 at Anthropic's legal request ([PR #18186](https://github.com/anomalyco/opencode/pull/18186)). Anthropic models still work fine — via an **API key** in the provider config below, or via **Zen**.
+
#### Direct provider config
```json
{
"$schema": "https://opencode.ai/config.json",
- "model": "anthropic/claude-sonnet-4-5",
+ "model": "anthropic/claude-sonnet-5",
"provider": {
"anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } },
"openai": { "options": { "apiKey": "{file:~/.secrets/openai-key}" } }
@@ -201,7 +209,7 @@ Per-agent model override:
{
"agent": {
"plan": { "model": "anthropic/claude-haiku-4-5" },
- "deep-thinker": { "model": "openai/gpt-5", "options": { "reasoningEffort": "high" } }
+ "deep-thinker": { "model": "openai/gpt-5.5", "options": { "reasoningEffort": "high" } }
}
}
```
@@ -217,23 +225,30 @@ A curated, pay-as-you-go AI gateway. The OpenCode team tests and tunes models fo
/models # browse the lineup
```
-**Pricing snapshot** *(verified 2026-06-08; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
+**Pricing snapshot** *(verified 2026-07-05; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
| Model ID | Input / Output (per MTok) | Reach for it when… |
|---|---|---|
+| `opencode/claude-fable-5` | $10 / $50 | Absolute frontier — the hardest reasoning problems |
| `opencode/claude-opus-4-8` | $5 / $25 | Flagship reasoning — complex refactors, large multi-file work |
-| `opencode/claude-sonnet-4-6` | $3 / $15 | Balanced everyday coding |
+| `opencode/claude-sonnet-5` | $2 / $10 | Balanced everyday coding — newer *and* cheaper than Sonnet 4.6 |
| `opencode/claude-haiku-4-5` | $1 / $5 | Fast, lightweight tasks |
| `opencode/gpt-5.5` *(≤272K)* | $5 / $30 | Long-context, OpenAI ecosystem |
| `opencode/gpt-5.4-mini` | $0.75 / $4.50 | Cost-efficient frontier |
-| `opencode/gemini-3.1-pro` | $2 / $12 | Multimodal, Google ecosystem |
+| `opencode/gemini-3.1-pro` *(≤200K)* | $2 / $12 | Multimodal, Google ecosystem |
| `opencode/qwen3.7-plus` | $0.40 / $1.60 | Budget-friendly heavy lifting |
-**Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `nemotron-3-ultra-free`.
+**Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `north-mini-code-free`, `nemotron-3-ultra-free`.
+
+> 📚 Full lineup, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, DeepSeek, Grok, and the Claude Opus 4.8/4.7/4.6/4.5 line: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide (incl. deprecation sunset dates): [`docs/zen.md`](docs/zen.md).
-> 50+ models total — full list, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, Grok, and the Claude Opus 4.8/4.7/4.5/4.1 line: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide: [`docs/zen.md`](docs/zen.md).
+> 💡 **Pattern: cheap explorer / strong executor.** Use a cheap model (`qwen3.7-plus`, `gpt-5.4-mini`) for `explore` and `scout` subagents that read a lot, and a stronger one (`claude-sonnet-5` or `claude-opus-4-8`) for the main `build` agent that does the editing.
-> 💡 **Pattern: cheap explorer / strong executor.** Use a cheap model (`qwen3.7-plus`, `gpt-5.4-mini`) for `explore` and `scout` subagents that read a lot, and a stronger one (`claude-sonnet-4-6` or `claude-opus-4-8`) for the main `build` agent that does the editing.
+#### OpenCode Go
+
+The flat-rate alternative to Zen: **$10/month ($5 your first month)** for a curated set of hosted open coding models — no API keys, no per-token math. Usage limits apply (roughly $12 per 5 hours / $30 per week / $60 per month of equivalent usage); past them, Go can fall back to a Zen balance.
+
+**Zen vs. Go in one line:** Zen bills per token across the full lineup; Go is a fixed subscription to open models. Reach for Go to learn and hack on a predictable budget; reach for Zen (or direct keys) when you want frontier models. Details: [opencode.ai/docs/go](https://opencode.ai/docs/go/) · [`docs/zen.md`](docs/zen.md).
---
@@ -262,7 +277,7 @@ Natural workflow:
(implements, edits, runs tests)
```
-> 💡 Prompts like `think hard`, `think more`, or `ultrathink` nudge reasoning depth on supported models — the same pattern in the [Anthropic prompt engineering guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).
+> 💡 Prompts like `think hard`, `think more`, or `ultrathink` nudge reasoning depth on supported models — the same pattern in the [Anthropic prompt engineering guide](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/overview).
#### File references and shell
@@ -362,7 +377,7 @@ opencode github install # add a workflow file to your repo
opencode pr 123 # check out PR #123 and start a session
```
-Useful `run` flags: `--continue` / `--session ` (resume), `--fork` (branch a session), `--share` (publish), `--format json` (machine-readable), `--file ` (attach), `--replay` (interactive replay, v1.16+), `--dangerously-skip-permissions` (auto-approve everything not `deny` — **CI only**).
+Useful `run` flags: `--continue` / `--session ` (resume), `--fork` (branch a session), `--share` (publish), `--format json` (machine-readable), `--file ` (attach), `--replay` (interactive replay, v1.16+), `--auto` (auto-approve everything not `deny` — **CI only**). There's also a lightweight `--mini` mode (v1.17.10+).
Sessions, stats, sharing:
@@ -460,7 +475,7 @@ description: Run tests and triage failures
agent: build
---
-!pnpm test --reporter=verbose
+!`pnpm test --reporter=verbose`
If any tests failed above, open the failing files and propose precise fixes.
Otherwise, summarize the coverage.
@@ -479,7 +494,7 @@ Save as `.opencode/commands/test.md` → invoke with `/test`.
|---|---|
| `$ARGUMENTS` / `$1` / `$2` | Text after the command name |
| `@` | File content (fuzzy resolved) |
-| `` `!` `` | Shell stdout |
+| ``!`` `` | Shell stdout (backticks required in templates) |
This repo ships four examples in [`.opencode/commands/`](.opencode/commands/): `/review`, `/pr`, `/test`, `/optimize`.
@@ -568,7 +583,7 @@ Drop a markdown file in `.opencode/agents/`:
---
description: Senior frontend engineer — Tailwind + React + TypeScript
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
permission:
edit: allow
bash:
@@ -648,7 +663,7 @@ Featured walkthroughs in [`mcp-servers/`](./mcp-servers/):
*[→ Full FAQ in `docs/reference/faq.md`](docs/reference/faq.md)*
**Is OpenCode free?**
-The software is open source (MIT). You pay for whichever LLM provider you use. [OpenCode Zen](#opencode-zen) is pay-as-you-go starting at fractions of a cent per request; BYOK works for direct providers.
+The software is open source (MIT). You pay for whichever LLM provider you use. [OpenCode Zen](#opencode-zen) is pay-as-you-go per token; [OpenCode Go](#opencode-go) is a flat $10/month for hosted open models; BYOK works for direct providers.
**Does OpenCode work without an internet connection?**
Yes, with a local model (Ollama, LM Studio, llama.cpp). Network is needed for hosted providers, remote MCP servers, sharing, and updates.
@@ -671,23 +686,24 @@ Set `bash` permission to `"ask"` at the project level, or use the glob form to w
*[→ Full changelog in `docs/reference/changelog.md`](docs/reference/changelog.md)*
-**Current release:** **v1.16.2** *(2026-06-05)*. Run `opencode upgrade` to get it.
+**Current release:** **v1.17.13** *(2026-07-01)*. Run `opencode upgrade` to get it.
-**New in v1.16:**
+**New in v1.17:**
-- 🆕 **File-based agents & skill discovery** — drop-in agent markdown files and `SKILL.md` discovery are GA; scaffold an agent with `opencode agent create`.
-- 🆕 **Workspace cloning & session mobility** — managed workspace clones keep dirty/untracked files, and you can move sessions between workspaces and directories.
-- 🆕 **`opencode run --replay`** — interactively replay a run as it streams.
-- 🆕 **OpenAI models via AWS Bedrock** — plus GitHub Copilot token-based usage tracking.
-- ⚡ **~38% faster startup**, and a desktop app refresh (color themes, thinking-level selector, Servers tab).
+- 🆕 **Session snapshots & revert** *(v1.17.11)* — roll a session back to an earlier message, including the file changes it made.
+- 🆕 **TUI yolo mode** *(v1.17.12)* — auto-approve permission prompts from inside the TUI; plus adaptive thinking for Claude Sonnet 5.
+- 🆕 **MCP resources** *(v1.17.10)* — resource template listing and resource-read tools, and MCP server instructions now land in session context. Local servers also gained a `cwd` option *(v1.17.4)*.
+- 🆕 **`--mini` CLI mode & V2 plugin API** *(v1.17.10)* — a lightweight CLI surface, namespaced plugin hooks, and Effect/Promise plugin support.
+- ⚡ **Faster file search** (new `fff`-backed tools), WSL-backed desktop on Windows, and a desktop v2 refresh (Chrome-style tabs, searchable model picker) *(v1.17.0–v1.17.13)*.
+- ⚠️ **Deprecation:** the `reference` config key is now `references` *(v1.17.1; old entries still load)*.
-**Still recent (v1.15):**
+**Still recent (v1.16):**
-- **Glob-pattern bash permissions** — fine-grained allow/ask/deny per command pattern (rules match in order, last match wins).
-- **Remote MCP with auto-OAuth** — Dynamic Client Registration handled out of the box.
-- **ACP server (`opencode acp`)** — Agent Client Protocol for editor integrations.
-- **Managed configs** — macOS `/Library/Application Support/opencode/`, Linux `/etc/opencode/`, Windows `%ProgramData%\opencode`, plus macOS MDM preferences.
-- 📝 **AGENTS.md** is canonical; `CLAUDE.md` is now a fallback only.
+- **File-based agents & skill discovery** — drop-in agent markdown files and `SKILL.md` discovery are GA; scaffold an agent with `opencode agent create`.
+- **Workspace cloning & session mobility** — managed workspace clones keep dirty/untracked files; move sessions between workspaces and directories.
+- **`opencode run --replay`** — interactively replay a run as it streams.
+- **~38% faster startup**, OpenAI models via AWS Bedrock, GitHub Copilot usage tracking.
+- 📝 **AGENTS.md** is canonical; `CLAUDE.md` is a fallback only.
> 💡 Source of truth: [GitHub releases](https://github.com/anomalyco/opencode/releases).
@@ -711,4 +727,6 @@ Set `bash` permission to `"ask"` at the project level, or use the glob form to w
> Features, pricing, and availability change frequently. Always check the [official OpenCode documentation](https://opencode.ai/docs/) for the most current information.
-*Last reviewed 2026-06-08 · OpenCode v1.16.2 · Spotted something stale? [Open an issue](../../issues) or send a PR — see [`CONTRIBUTING.md`](CONTRIBUTING.md).*
+*Last reviewed 2026-07-05 · OpenCode v1.17.13 · Spotted something stale? [Open an issue](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/issues) or send a PR — see [`CONTRIBUTING.md`](CONTRIBUTING.md).*
+
+**Found this useful? [Give it a ⭐](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know) — it's how other developers discover the guide.**
diff --git a/SECURITY.md b/SECURITY.md
index 655b79a..475799d 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -17,7 +17,7 @@ If you find a security issue in:
| Where | Report to |
|---|---|
| **OpenCode itself** (the tool) | Open a [security advisory on `anomalyco/opencode`](https://github.com/anomalyco/opencode/security/advisories/new) |
-| **The example plugins in this repo** | Open a confidential issue or contact the maintainer directly via GitHub |
+| **The example plugins in this repo** | Use GitHub's [private vulnerability reporting](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/security/advisories/new) ("Report a vulnerability" under the repo's Security tab) |
| **A factual error in documentation** that could mislead a user into a vulnerable configuration | Open a normal issue or PR |
Please **don't** disclose security issues publicly until they've been addressed. We'll acknowledge receipt within 7 days and aim to resolve within 30.
diff --git a/docs/agents.md b/docs/agents.md
index d39186d..3cadef4 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -25,13 +25,13 @@ Two locations, same format:
| Project | `.opencode/agents/.md` |
| Global | `~/.config/opencode/agents/.md` |
-> 🆕 File-based agent loading is GA as of v1.16. Scaffold one interactively with `opencode agent create` (it prompts for location, description, mode, model, and permissions), or just write the markdown by hand.
+> 🆕 File-based agent loading is GA as of v1.16. Scaffold one interactively with `opencode agent create` (it prompts for location, description, mode, and permissions), or just write the markdown by hand.
```markdown
---
description: Senior frontend engineer — Tailwind + React + TypeScript expert
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.2
permission:
edit: allow
@@ -72,7 +72,7 @@ Verified against the [config JSON schema's `AgentConfig`](https://opencode.ai/co
| `color` | string | UI accent color |
| `variant` · `options` | string · object | Model variant + per-provider options |
-Only `description` and `mode` are required.
+Only `description` is effectively required — `mode` is optional and defaults to `all`.
### Filename → agent name
@@ -198,7 +198,7 @@ A daily-driver agent with a baked-in role. Different model, different prompt, di
---
description: Backend engineer — TypeScript, Postgres, REST
mode: primary
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
permission:
bash:
"*": "ask"
@@ -230,3 +230,7 @@ permission:
This repo ships 7 production-ready prompts in [`specialized-agents/`](../specialized-agents/) — backend, frontend, code reviewer, security reviewer, tech lead, database, and UX. Copy any of them to `.opencode/agents/.md` to use as a starting point.
> 📚 Full agent reference: [opencode.ai/docs/agents](https://opencode.ai/docs/agents).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/agents](https://opencode.ai/docs/agents).*
diff --git a/docs/commands.md b/docs/commands.md
index c0e81ff..b78852f 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -4,7 +4,7 @@
## When to use a command vs. a skill vs. an agent
-| | Custom Command | Agent Skill | Custom Agent |
+| | Custom Command | [Agent Skill](skills.md) | [Custom Agent](agents.md) |
|---|---|---|---|
| Invocation | **Manual** — user types `/` | **Auto** — model loads when description matches | Mode-dependent (Tab or `@`) |
| Best for | Repeatable user-driven prompts | Domain expertise the model should discover | A persistent role / tool surface |
@@ -18,7 +18,7 @@ A good rule of thumb: **commands run a workflow; skills teach the agent how to h
---
description: Run tests with coverage and triage failures
agent: build
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
subtask: false
---
@@ -32,10 +32,12 @@ Arguments: $ARGUMENTS
| Key | Type | Required | Purpose |
|---|---|---|---|
-| `description` | string | yes | One-liner shown in the slash-command palette |
+| `description` | string | no (recommended) | One-liner shown in the slash-command palette |
| `agent` | string | no | Which agent runs the command (`build`, `plan`, or custom) |
| `model` | `provider/model-id` | no | Override model just for this command |
-| `subtask` | bool | no | If `true`, runs as a subagent (fresh, isolated context) |
+| `subtask` | bool | no | If `true`, runs the specified agent in an isolated child session |
+
+Only the template body is required — a command file with no frontmatter at all is still a valid command.
### Body placeholders
@@ -44,10 +46,12 @@ Arguments: $ARGUMENTS
| `$ARGUMENTS` | Everything after the command name |
| `$1`, `$2`, … | Positional args (whitespace-split) |
| `@` | File content (fuzzy resolved) |
-| `` `!` `` | Shell stdout |
+| ``!`` `` | Shell stdout |
Placeholders are resolved **at invocation time**, so each run picks up fresh file content and shell output.
+Note the shell-injection syntax is bang **plus backticks** — ``!`cmd` ``. A bare `!cmd` only works as a TUI prompt prefix, not inside command templates.
+
## Where commands live
| Scope | Path |
@@ -67,7 +71,7 @@ description: Run tests, triage failures
agent: build
---
-!pnpm test --reporter=verbose
+!`pnpm test --reporter=verbose`
If any tests failed above, open the relevant source files and propose a fix.
Otherwise, summarize coverage and any flaky-looking tests.
@@ -81,7 +85,7 @@ description: Review changed files for the current branch
agent: plan
---
-!git diff --name-only main...HEAD
+!`git diff --name-only main...HEAD`
Review each changed file above for security, perf, and style. Suggest fixes
with code snippets — but do not edit files. Prioritize anything under
@@ -129,7 +133,7 @@ Produce a report with findings and recommendations. Run as a subagent —
your work won't pollute the main session's context.
```
-`subtask: true` runs the prompt as a `general` subagent in a child session, so the heavy reading and analysis stays separate from your main conversation.
+`subtask: true` runs the **specified agent** (here `build`) in an isolated child session, so the heavy reading and analysis stays separate from your main conversation.
## Patterns
@@ -168,3 +172,7 @@ OpenCode's built-in commands (`/init`, `/help`, `/share`, etc. — see [`referen
> ⚠️ Override sparingly. If you replace `/help`, users in your repo lose access to the real help dialog. Pick a unique name like `/repo-help` instead.
> 📚 Full Commands guide: [opencode.ai/docs/commands](https://opencode.ai/docs/commands).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/commands](https://opencode.ai/docs/commands).*
diff --git a/docs/mcp.md b/docs/mcp.md
index a94bdf9..2d5bda5 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -53,7 +53,7 @@ OpenCode supports both, declared in `opencode.json` under `mcp`.
"type": "local",
"command": ["npx", "-y", "@playwright/mcp@latest"],
"enabled": true,
- "environment": { "BROWSER_TYPE": "chromium" },
+ "environment": { "PLAYWRIGHT_MCP_BROWSER": "chromium" },
"timeout": 5000
}
}
@@ -66,6 +66,7 @@ OpenCode supports both, declared in `opencode.json` under `mcp`.
| `command` | yes | Array form — argv-style |
| `enabled` | no | Default `true`; set `false` to keep the entry but disable it |
| `environment` | no | Extra env vars for the subprocess |
+| `cwd` | no | Working directory for the spawned subprocess (v1.17.4+) |
| `timeout` | no | Tool-call timeout (ms). Default 5000. |
### Remote servers — HTTP
@@ -88,6 +89,8 @@ OpenCode supports both, declared in `opencode.json` under `mcp`.
| `url` | yes | HTTPS endpoint |
| `headers` | no | Custom HTTP headers (supports `{env:NAME}`) |
| `oauth` | no | Pre-registered OAuth client credentials |
+| `enabled` | no | Default `true`; set `false` to keep the entry but disable it |
+| `timeout` | no | Tool-call timeout (ms). Default 5000. |
## OAuth
@@ -161,14 +164,23 @@ Disable noisy tools at the project level and re-enable them only for agents that
## Featured servers
-This repo has walkthroughs for several MCP servers in [`../mcp-servers/`](../mcp-servers/).
+### Walkthroughs in this repo
+
+Step-by-step setup guides live in [`../mcp-servers/`](../mcp-servers/):
+
+| Server | Adds | Type | Walkthrough |
+|---|---|---|---|
+| **Playwright** | Browser automation (DOM, network, screenshots, accessibility) | local | [`playwright.md`](../mcp-servers/playwright.md) |
+| **Context7** | Live, version-pinned library docs | remote | [`context7.md`](../mcp-servers/context7.md) |
+| **Sentry** | Errors, traces, releases | remote (OAuth) | [`sentry.md`](../mcp-servers/sentry.md) |
+| **Grep by Vercel** | Code search across GitHub | remote | [`grep.md`](../mcp-servers/grep.md) |
+
+> ⚠️ **Warning:** the `mcp.grep.app` endpoint has been flaky (returning 504 as of 2026-07-05). See the [walkthrough](../mcp-servers/grep.md) and Vercel's [announcement post](https://vercel.com/blog/grep-a-million-github-repositories-via-mcp) for details.
+
+### Other notable servers
| Server | Adds | Type | Source |
|---|---|---|---|
-| **Playwright** | Browser automation (DOM, network, screenshots, accessibility) | local | [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) |
-| **Context7** | Live, version-pinned library docs | remote | [`upstash/context7`](https://github.com/upstash/context7) |
-| **Sentry** | Errors, traces, releases | remote (OAuth) | [`mcp.sentry.dev`](https://mcp.sentry.dev/) |
-| **Grep by Vercel** | Code search across GitHub | remote | [`mcp.grep.app`](https://mcp.grep.app/) |
| **Chrome DevTools** | Drive a real Chrome instance | local | [`ChromeDevTools/chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
| **Memory / mem0** | Long-term cross-session memory | local/remote | [`mem0ai/mem0`](https://github.com/mem0ai/mem0) |
| **Tavily** | Web search + extraction for agents | remote | [`tavily-ai/tavily-mcp`](https://github.com/tavily-ai/tavily-mcp) |
@@ -184,6 +196,10 @@ look up the React Router v7 changelog (use context7)
search the codebase for `parseToken` calls with grep
```
+## MCP resources
+
+> 🆕 As of [v1.17.10](https://github.com/anomalyco/opencode/releases/tag/v1.17.10), OpenCode exposes MCP **resources**, not just tools: it can list a server's resource templates and read individual resources through dedicated tools. Instructions published by an MCP server are also appended to the session context automatically.
+
## Discovery — the MCP Registry
The [Official MCP Registry](https://registry.modelcontextprotocol.io/) (live since 2025) catalogues vetted servers. Browse via the website or look for `opencode mcp` discovery features in newer versions.
@@ -199,3 +215,7 @@ The [Official MCP Registry](https://registry.modelcontextprotocol.io/) (live sin
| Connection times out | Bump `timeout` (default 5000ms) |
> 📚 Full MCP guide: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers) · Registry: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) · Protocol spec: [modelcontextprotocol.io](https://modelcontextprotocol.io/).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers).*
diff --git a/docs/migration.md b/docs/migration.md
index b86b90c..b0415b3 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -35,11 +35,15 @@ If those matter more to you than multi-provider flexibility or full open source,
| `CLAUDE.md` for project rules | `AGENTS.md` (falls back to `CLAUDE.md` for compatibility) |
| `.claude/commands/.md` | `.opencode/commands/.md` |
| `.claude/skills//SKILL.md` | `.opencode/skills//SKILL.md` *(but also reads from `.claude/skills/`)* |
-| `.claude/settings.json` hooks (Python scripts on lifecycle events) | `.opencode/plugins/.{js,ts}` (JS/TS modules on events) |
+| `.claude/settings.json` hooks (shell commands on lifecycle events) | `.opencode/plugins/.{js,ts}` (JS/TS modules on events) |
| `.claude/agents/.md` | `.opencode/agents/.md` (similar markdown+YAML format, different fields) |
| `claude` CLI | `opencode` CLI |
| `/auth login` | `opencode auth login` or `/connect` |
+### Note on Claude Pro/Max subscriptions
+
+Since 2026-03-19, OpenCode no longer ships built-in Claude Pro/Max subscription OAuth — it was removed at Anthropic's legal request ([PR #18186](https://github.com/anomalyco/opencode/pull/18186)). Your subscription still works in Claude Code, but it can't authenticate OpenCode. To use Anthropic models in OpenCode, bring an Anthropic API key (the `anthropic` provider) or go through [Zen](zen.md).
+
### Migration steps
```bash
@@ -53,7 +57,7 @@ opencode auth login # pick a provider (Anthropic, Zen, OpenAI, etc.)
git mv .claude/commands .opencode/commands # if you had commands
git mv .claude/skills .opencode/skills # if you had skills
git mv .claude/agents .opencode/agents # but see agent format note below
-mv CLAUDE.md AGENTS.md # rename — OpenCode prefers AGENTS.md
+git mv CLAUDE.md AGENTS.md # rename — OpenCode prefers AGENTS.md
# 4. Disable the Claude fallback once migrated
export OPENCODE_DISABLE_CLAUDE_CODE=1
@@ -81,7 +85,7 @@ OpenCode uses:
---
description: ...
mode: subagent
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
permission:
edit: deny
bash: ask
@@ -97,7 +101,7 @@ Key changes:
### Hooks → Plugins
-Claude Code uses Python scripts triggered by `.claude/settings.json`. OpenCode uses JS/TS modules in `.opencode/plugins/`. Behaviorally similar, syntactically different.
+Claude Code hooks are shell commands configured in `settings.json` (often scripts). OpenCode uses JS/TS modules in `.opencode/plugins/`. Behaviorally similar, syntactically different.
Claude Code `pre_tool_use.py`:
@@ -228,4 +232,4 @@ Migration is mostly muscle-memory adjustment, not config porting.
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/plugins.md b/docs/plugins.md
index c379f95..adefaec 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -57,7 +57,7 @@ opencode plugin --global opencode-wakatime
## Plugin API
-A plugin is a default-export async function returning an object of **hooks**. There are two shapes: typed hooks like `tool.execute.before` that receive `(input, output)`, and a generic `event` handler that receives the lifecycle event stream:
+A plugin is an exported async function returning an object of **hooks** — named exports work fine, and every exported function in the file is loaded. There are two shapes: typed hooks like `tool.execute.before` that receive `(input, output)`, and a generic `event` handler that receives the lifecycle event stream:
```javascript
// .opencode/plugins/notify-on-idle.js
@@ -96,6 +96,10 @@ Verified against the [Plugins doc](https://opencode.ai/docs/plugins):
| `tool.execute.after` | After a tool completes | `input.tool`, `input.args`; `output.title` / `output.output` |
| `shell.env` | Resolving shell environment | `input.cwd`; `output.env` (mutable) |
+There's also a `tool` key for registering **custom tool definitions** from a plugin — the agent sees them alongside the built-in tools.
+
+> 🆕 [v1.17.10](https://github.com/anomalyco/opencode/releases/tag/v1.17.10) added namespaced plugin hook APIs and a V2 plugin API supporting both Effect and Promise plugins.
+
**Event stream** — `event: async ({ event }) => { if (event.type === …) }`:
| Category | `event.type` values |
@@ -231,3 +235,7 @@ opencode debug # debug subcommands
Plugin errors show up in the TUI; full traces appear in OpenCode's log (default at `~/.local/share/opencode/log/`, or stderr with `--print-logs`).
> 📚 Full Plugins guide and event reference: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).*
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 216796f..cc11fe1 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -77,26 +77,30 @@ Two character prefixes that change how you talk to OpenCode in prompts:
| Prefix | Purpose | Example |
|---|---|---|
| `@` | Attach a file's content (fuzzy resolved) | `look at @src/api/auth.ts` |
-| `!` | Run shell, inject output | `!git diff` then ask Claude about it |
+| `!` | Run shell, inject output | `!git diff` then ask the model about it |
## What next?
- **[Custom Commands](commands.md)** — turn prompts into `/` shortcuts (~3 min)
- **[OpenCode Zen](zen.md)** — model picks, pricing, and BYOK
- **[Agents](agents.md)** — custom build/plan variants and subagents
+- **[Agent Skills](skills.md)** — workflows the agent discovers and loads on its own
+- **[Plugins](plugins.md)** — run code automatically on lifecycle events
- **[MCP](mcp.md)** — plug in external tools (browsers, DBs, search)
## Common first-day issues
**`opencode: command not found`**
-Add the install path to your shell config:
+The install script puts the binary in `~/.opencode/bin`. Add it to your shell config:
```bash
-echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
+echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
source ~/.zshrc
```
+(If you installed via `npm i -g`, the binary lands in npm's global bin directory instead — usually already on your `PATH`.)
+
**Auth fails with "no provider configured"**
Run `opencode auth login` and pick a provider. Re-run `/connect` from inside the TUI if you want to add another.
@@ -105,9 +109,9 @@ Run `opencode auth login` and pick a provider. Re-run `/connect` from inside the
```bash
opencode upgrade # latest
-opencode upgrade v1.16.0 # specific version
+opencode upgrade v1.17.13 # specific version
```
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md
index 09cfca3..022874b 100644
--- a/docs/reference/changelog.md
+++ b/docs/reference/changelog.md
@@ -4,11 +4,26 @@
This document tracks **what's new at a high level** — the things that change how you use OpenCode. Bug fixes and small polish items aren't listed here.
-## v1.16.x — June 2026
+## v1.17.x — June–July 2026
Current stable line. Run `opencode upgrade` to get the latest.
-**Verified latest release:** `v1.16.2`, published 2026-06-05 ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.16.2)). The headline features shipped in `v1.16.0` the same day.
+**Verified latest release:** `v1.17.13`, published 2026-07-01 ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.17.13)).
+
+**Highlights:**
+
+- **Session snapshots & revert** (`v1.17.11`) — roll a session back to an earlier message, including file changes; plus desktop Chrome-style tabs (mod+1–9).
+- **TUI yolo mode** (`v1.17.12`) — auto-approve permissions from inside the TUI; plus adaptive thinking for Claude Sonnet 5.
+- **`--mini` CLI mode, MCP resources, V2 plugin API** (`v1.17.10`) — MCP resource template listing + resource read tools, MCP server instructions appended to session context, and a V2 plugin API (Effect and Promise plugins).
+- **Agent `steps` limits honored** (`v1.17.9`) — hitting the limit forces a final text response instead of failing mid-run.
+- **`cwd` option for local MCP servers** (`v1.17.4`) — plus connector-based auth and stored provider credentials.
+- **Faster file search (fff-backed), WSL-backed Desktop on Windows, Cohere North models** (`v1.17.0`) — plus non-interactive `opencode mcp add`.
+- **`reference` config key renamed to `references`** (`v1.17.1`) — the old key still loads; see Deprecations below.
+- **Searchable v2 model picker in the desktop composer** (`v1.17.13`) — plus session tab hover preview.
+
+## v1.16.x — June 2026
+
+**Latest:** `v1.16.2`, published 2026-06-05 ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.16.2)). The headline features shipped in `v1.16.0` the same day.
**Highlights:**
@@ -71,8 +86,9 @@ For the current state, check the [GitHub repo](https://github.com/anomalyco/open
## Deprecations
+- `reference` config key — renamed to `references` in `v1.17.1`. (The old key still loads.)
- `CLAUDE.md` as a primary instructions file — use `AGENTS.md`. (Fallback still works; disable with `OPENCODE_DISABLE_CLAUDE_CODE=1`.)
---
-*Last reviewed: 2026-06-08 · For the authoritative list, see [GitHub releases](https://github.com/anomalyco/opencode/releases) · Canonical docs: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · For the authoritative list, see [GitHub releases](https://github.com/anomalyco/opencode/releases) · Canonical docs: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 4c122c6..aab9d0a 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -41,6 +41,7 @@ opencode [project] [flags]
| `--port`, `--hostname` | Bind the underlying server |
| `--mdns`, `--mdns-domain` | mDNS discovery |
| `--cors ` | Additional browser origins for CORS |
+| `--mini` | Start the TUI in mini mode *(v1.17.10+, per the [release notes](https://github.com/anomalyco/opencode/releases/tag/v1.17.10))* |
---
@@ -74,7 +75,7 @@ opencode run --agent plan --model anthropic/claude-haiku-4-5 "audit src/ for mis
| `--replay` | Interactively replay the run as it streams *(v1.16+)* |
| `--replay-limit ` | How much recent history to show when replaying |
| `--command ` | Run a saved command |
-| `--dangerously-skip-permissions` | Auto-approve everything that isn't explicitly denied. **CI only.** |
+| `--auto` | Auto-approve everything that isn't explicitly denied. **CI only.** |
---
@@ -285,7 +286,7 @@ Update OpenCode to the latest or a specific version.
```bash
opencode upgrade
-opencode upgrade v1.16.0
+opencode upgrade v1.17.13
opencode upgrade --method brew # force the install method
```
@@ -311,3 +312,7 @@ opencode uninstall [--keep-config] [--keep-data] [--dry-run] [--force]
| `--force`, `-f` | Skip confirmation |
> 📚 Full live CLI reference: [opencode.ai/docs/cli](https://opencode.ai/docs/cli).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/cli](https://opencode.ai/docs/cli).*
diff --git a/docs/reference/faq.md b/docs/reference/faq.md
index dffd8b8..26303e9 100644
--- a/docs/reference/faq.md
+++ b/docs/reference/faq.md
@@ -10,6 +10,15 @@ The software is free and open-source (MIT). You pay for whichever LLM provider y
- **Direct providers** — your own Anthropic/OpenAI/Google/etc. account; pricing is whatever they charge.
- **Local models** — free if you're running Ollama/LM Studio/llama.cpp on your own hardware.
+### Q: What's the difference between OpenCode Zen and OpenCode Go?
+
+Both are hosted model access from the OpenCode team — the difference is billing:
+
+- **Zen** — pay-as-you-go, per-token gateway across the full curated lineup (Anthropic, OpenAI, Google, open models). You pay for exactly what you use.
+- **Go** — a flat **$10/month subscription ($5 the first month)** to a curated set of hosted open models. Usage limits apply ($12 per 5 hours, $30/week, $60/month equivalent); past the limits it can fall back to a Zen balance.
+
+Reach for Go when you want a predictable monthly bill on open models; reach for Zen when you want per-token access to everything. See [opencode.ai/docs/go](https://opencode.ai/docs/go/) and [`../zen.md`](../zen.md).
+
### Q: What's the difference between OpenCode and Claude Code?
Briefly: OpenCode is **provider-agnostic and open source**; Claude Code is **Anthropic-only and proprietary**.
@@ -20,10 +29,14 @@ Briefly: OpenCode is **provider-agnostic and open source**; Claude Code is **Ant
| Models | Any provider | Anthropic only |
| Pricing | Pay-as-you-go or BYOK | Subscription |
| Config | `opencode.json` + `.opencode/` | `.claude/settings.json` + `.claude/` |
-| Hooks | JS/TS plugins | Python scripts |
+| Hooks | JS/TS plugins | Shell commands (often scripts) |
OpenCode reads `CLAUDE.md` and `.claude/skills/` as fallbacks for easier migration.
+### Q: Can I sign in with my Claude Pro/Max subscription?
+
+No. The built-in Anthropic subscription OAuth (the `opencode-anthropic-auth` plugin) was removed on 2026-03-19 at Anthropic's legal request ([PR #18186](https://github.com/anomalyco/opencode/pull/18186)). Anthropic models still work in OpenCode — use an Anthropic **API key** (the `anthropic` provider with `apiKey`) or route through **Zen** (`opencode/claude-…` models).
+
### Q: Does OpenCode work offline?
Yes, if you point it at a local model (Ollama, LM Studio, llama.cpp). Internet access is needed for hosted providers, remote MCP servers, sharing, and updates.
@@ -34,12 +47,12 @@ Honest answer: **try a few on your actual workload.** Benchmarks generalize poor
| Task | Reasonable options |
|---|---|
-| Day-to-day coding | Claude Sonnet (4.5 direct or 4.6 via Zen), GPT-5.4, Gemini 3.1 Pro |
-| Complex multi-file refactors | Claude Opus 4.7, GPT-5.5, GPT-5.5 Pro |
+| Day-to-day coding | Claude Sonnet 5 (direct or `opencode/claude-sonnet-5`, $2/$10), GPT-5.4, Gemini 3.1 Pro |
+| Complex multi-file refactors | Claude Fable 5, Claude Opus 4.8, GPT-5.5, GPT-5.5 Pro |
| Fast, lightweight tasks | Claude Haiku 4.5, GPT-5.4 Mini, GPT-5.4 Nano, GLM/Kimi |
-| Long-context (>200K tokens) | GPT-5.5 (272K), Claude Sonnet 4.5/4 (>200K tier) |
-| Budget-friendly | Qwen3.6 Plus, GPT-5.4 Nano, Qwen3.5 Plus, MiniMax M2.7 |
-| Local / offline | Ollama or LM Studio with a coding-tuned model that fits your hardware (Qwen 2.5 Coder, DeepSeek Coder, CodeLlama — quality varies hugely with model size and quantization) |
+| Long-context (>200K tokens) | GPT-5.5 (272K), Gemini 3.1 Pro (>200K tier) |
+| Budget-friendly | Qwen3.7 Plus, GPT-5.4 Nano, MiniMax M3 |
+| Local / offline | Ollama or LM Studio with a coding-tuned model that fits your hardware (a current Qwen coder or DeepSeek release — quality varies hugely with model size and quantization) |
Use a cheaper model for `explore`/`scout` subagents — they read a lot but don't need to write. See [`../zen.md`](../zen.md) for full pricing and the cheap-explorer / strong-executor pattern.
@@ -117,7 +130,7 @@ curl -fsSL https://opencode.ai/install | bash
opencode run --agent plan --format json "audit src/ for security issues" > findings.json
```
-For unattended runs, `--dangerously-skip-permissions` auto-approves anything that isn't explicitly denied — only after auditing what your prompt and tools can do.
+For unattended runs, `--auto` auto-approves anything that isn't explicitly denied — only after auditing what your prompt and tools can do.
### Q: Can I attach a remote OpenCode server?
@@ -152,7 +165,7 @@ See [`../migration.md`](../migration.md) for the full guide. Quick version:
- Rename `CLAUDE.md` → `AGENTS.md`
- Move `.claude/commands/` → `.opencode/commands/`
- Move `.claude/skills/` → `.opencode/skills/`
-- Rewrite Python hooks as JS/TS plugins in `.opencode/plugins/`
+- Rewrite shell-command hooks as JS/TS plugins in `.opencode/plugins/`
- Update agent frontmatter — different field names
### Q: Do my Cursor rules work?
@@ -201,7 +214,7 @@ Three layers:
Add the install path to your shell:
```bash
-echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
@@ -249,4 +262,4 @@ export EDITOR='nvim' # Neovim
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/reference/further-reading.md b/docs/reference/further-reading.md
index 7541855..982a5fa 100644
--- a/docs/reference/further-reading.md
+++ b/docs/reference/further-reading.md
@@ -38,13 +38,13 @@
## Adjacent AI coding tools (for comparison or coexistence)
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)** — Anthropic's CLI; shares the `.claude/skills/` and `CLAUDE.md` formats OpenCode reads as fallbacks
+- **[Claude Code](https://code.claude.com/docs/en/overview)** — Anthropic's CLI; shares the `.claude/skills/` and `CLAUDE.md` formats OpenCode reads as fallbacks
- **[Aider](https://aider.chat/)** — Earlier terminal AI coding tool
-- **[Cursor](https://cursor.sh/)** — VS Code fork with embedded AI
+- **[Cursor](https://cursor.com/)** — VS Code fork with embedded AI
## Provider docs (for direct-provider setup)
-- **[Anthropic API](https://docs.anthropic.com/en/api/getting-started)**
+- **[Anthropic API](https://platform.claude.com/docs/en/api/getting-started)**
- **[OpenAI API](https://platform.openai.com/docs)**
- **[Google AI / Gemini API](https://ai.google.dev/gemini-api/docs)**
- **[Groq](https://console.groq.com/docs)**
@@ -56,7 +56,7 @@
These aren't OpenCode-specific, but the patterns transfer.
-- **[Anthropic — Prompt engineering overview](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview)**
+- **[Anthropic — Prompt engineering overview](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/overview)**
- **[Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)**
- **[OpenAI — Prompt engineering guide](https://platform.openai.com/docs/guides/prompt-engineering)**
@@ -66,4 +66,4 @@ These aren't OpenCode-specific, but the patterns transfer.
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/reference/permissions.md b/docs/reference/permissions.md
index 12a796c..81eff34 100644
--- a/docs/reference/permissions.md
+++ b/docs/reference/permissions.md
@@ -165,15 +165,22 @@ Glob patterns work too — useful for MCP tools:
- All tools are **enabled by default**.
- Most permissions default to `"allow"` for the `build` agent.
- The built-in `plan` agent sets `edit` and `bash` to `"ask"` so analysis sessions can't surprise-write files.
-- `external_directory` is **opt-in** — files outside the project root require explicit `"allow"`.
+- `external_directory` and `doom_loop` default to `"ask"` — touching files outside the project root, or repeating the same tool call 3+ times, prompts for approval.
+- `*.env` files are **denied by default** (`*.env.example` is allowed).
## When to lock things down
| Scenario | Recommendation |
|---|---|
| Shared repo, multiple contributors | Commit a restrictive `opencode.json` so everyone's agent has the same guardrails |
-| CI / headless | Use `--dangerously-skip-permissions` only after auditing what the prompt can reach |
+| CI / headless | Use `--auto` (auto-approves everything not explicitly denied) only after auditing what the prompt can reach |
| Working with secrets | `external_directory: "deny"` plus a plugin that blocks edits to `.env`/`secrets/` |
| First time on a repo | Set `bash: "ask"` everywhere until you trust the workflows |
+> 🆕 v1.17.12 added TUI **yolo mode** — the interactive counterpart of `--auto`, auto-approving permission prompts from within the TUI. Same caveats apply.
+
> 📚 Live reference: [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions) and [opencode.ai/docs/agents](https://opencode.ai/docs/agents).
+
+---
+
+*Last reviewed: 2026-07-05.*
diff --git a/docs/reference/slash-commands.md b/docs/reference/slash-commands.md
index c43b039..be98dc3 100644
--- a/docs/reference/slash-commands.md
+++ b/docs/reference/slash-commands.md
@@ -56,3 +56,7 @@
Any markdown file in `.opencode/commands/.md` (or `~/.config/opencode/commands/`) creates a `/` slash command. See [`../commands.md`](../commands.md) for the file format.
> 📚 Source: [opencode.ai/docs/tui](https://opencode.ai/docs/tui). Built-in command set may evolve — check the docs for the current set.
+
+---
+
+*Last reviewed: 2026-07-05.*
diff --git a/docs/skills.md b/docs/skills.md
index 030036e..ba1d93d 100644
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -4,7 +4,7 @@
## Skill vs. Command — when to use which
-| | Agent Skill | Custom Command |
+| | Agent Skill | [Custom Command](commands.md) |
|---|---|---|
| Trigger | Agent decides (description match) | User types `/` |
| File | `.opencode/skills//SKILL.md` *(folder)* | `.opencode/commands/.md` *(file)* |
@@ -61,7 +61,7 @@ version bump before doing anything destructive.
| `name` | yes | `^[a-z0-9]+(-[a-z0-9]+)*$`, 1–64 chars — lowercase alphanumeric with single hyphens. **Must match the folder name** that contains `SKILL.md`. |
| `description` | yes | 1–1024 chars. **This is the discovery signal** — write it carefully. |
| `license` | no | SPDX identifier ideal |
-| `compatibility` | no | `opencode`, `claude-code`, or both |
+| `compatibility` | no | Open-ended string — e.g. `opencode` |
| `metadata` | no | String-to-string map (keys and values are both strings) |
### Why the `description` matters
@@ -95,7 +95,7 @@ OpenCode searches six locations — three project-local, three global:
| `~/.claude/skills//SKILL.md` | Global — Claude Code compatibility |
| `~/.agents/skills//SKILL.md` | Global — Agent-format compatibility |
-For the project paths, OpenCode traverses upward from the working directory to the git worktree root, so a skill in a parent folder is still found. Project skills take precedence over global; same-named skills resolve project-first.
+For the project paths, OpenCode traverses upward from the working directory to the git worktree root, so a skill in a parent folder is still found. Same-named skills resolve project-first.
## Permissions
@@ -178,6 +178,10 @@ Body: CLI invocation, common flags, what success and failure look like.
## Compatibility with Claude Code
-Skills using `compatibility: claude-code` work in both tools — OpenCode reads from `.claude/skills/`, Claude Code reads from there natively. Useful for teams running both.
+A skill in `.claude/skills/` works in both tools — OpenCode searches that path (see the table above), and Claude Code reads it natively. The sharing comes from the search path, not the `compatibility` value. Useful for teams running both.
> 📚 Full Skills guide: [opencode.ai/docs/skills](https://opencode.ai/docs/skills).
+
+---
+
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs/skills](https://opencode.ai/docs/skills).*
diff --git a/docs/tui.md b/docs/tui.md
index 71096a4..7eeadc4 100644
--- a/docs/tui.md
+++ b/docs/tui.md
@@ -45,7 +45,9 @@ Use the **leader key** (default `ctrl+x`) for session-level actions, and readlin
| `Tab` | Cycle primary agents (`build` ↔ `plan` ↔ custom primaries) |
| `shift+tab` | Cycle primary agents in reverse |
| `Esc` | Cancel / dismiss |
-| `ctrl+c` / `ctrl+d` | Exit |
+| `ctrl+c` / `ctrl+x q` | Exit |
+
+> 🆕 v1.17.12 added **yolo mode** — auto-approve permission prompts from within the TUI. See the [permissions reference](reference/permissions.md) before turning it on.
### Inside the prompt box (readline / emacs-style)
@@ -188,3 +190,7 @@ You can drag files (including images, for multimodal models) into the TUI. Image
| Costs rising | `opencode stats --days 7 --models` to find the offender |
> 📚 Full TUI reference: [opencode.ai/docs/tui](https://opencode.ai/docs/tui) · keybinds at [opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds).
+
+---
+
+*Last reviewed: 2026-07-05.*
diff --git a/docs/workflows.md b/docs/workflows.md
index 3c211c3..a24c80d 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -44,7 +44,7 @@ Goal: isolate context-heavy research from your main session.
[build] > /pr
```
-`@explore` and `@scout` run in **child sessions** — separate from your main session. Their long file reads and search output don't bloat the parent conversation. Navigate between parent and children with the session-child keybinds.
+`@explore` and `@scout` run in **child sessions** — separate from your main session. Their long file reads and search output don't bloat the parent conversation. Navigate between parent and child sessions with the [keybinds](https://opencode.ai/docs/keybinds) for session navigation.
## 3. Multi-agent review
@@ -157,7 +157,7 @@ opencode-review:
Same idea on Buildkite, CircleCI, Jenkins — install the CLI, set the env var, run a prompt, post the result wherever you post things.
-`--dangerously-skip-permissions` is available for fully unattended runs — use it with care.
+`--auto` is available for fully unattended runs — it auto-approves everything not explicitly denied, so use it with care.
> 🔧 **Native GitHub path.** Beyond the raw `curl | bash` recipe, OpenCode ships first-class GitHub commands: `opencode github install` wires up the GitHub App and workflow so `/opencode` (or `/oc`) mentions trigger the agent on issues and PRs, and `opencode pr ` checks out a PR branch locally and opens a session. As of v1.16, the GitHub extension refuses to commit without an existing git author identity — in Actions the runner already configures `user.name`/`user.email`, so the comment-only recipes above are unaffected.
@@ -174,7 +174,7 @@ Goal: implement UI to match a mock.
> compare the new screenshot to the mock and refine
```
-Two-three iteration rounds usually produces a close visual match. Multimodal models (`opencode/gemini-3.1-pro`, `opencode/claude-sonnet-4-6`) handle the comparison well.
+Two to three iteration rounds usually produce a close visual match. Multimodal models (`opencode/gemini-3.1-pro`, `opencode/claude-sonnet-4-6`) handle the comparison well.
## Cross-cutting tips
@@ -186,4 +186,4 @@ Two-three iteration rounds usually produces a close visual match. Multimodal mod
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/docs/zen.md b/docs/zen.md
index 0b91f69..dd0255d 100644
--- a/docs/zen.md
+++ b/docs/zen.md
@@ -2,7 +2,7 @@
> **Mental model:** Zen is OpenCode's curated, pay-as-you-go AI gateway. The OpenCode team tests and benchmarks models for coding-agent workloads and ships a focused lineup with consistent pricing.
>
-> *(Beta — verified against [opencode.ai/docs/zen](https://opencode.ai/docs/zen) on 2026-06-08. Pricing and model availability change frequently; check the docs before quoting numbers.)*
+> *(Beta — verified against [opencode.ai/docs/zen](https://opencode.ai/docs/zen) on 2026-07-05. Pricing and model availability change frequently; check the docs before quoting numbers.)*
## When to reach for Zen vs. direct providers
@@ -15,6 +15,19 @@
Zen is **opt-in**. OpenCode itself is provider-agnostic; you can mix Zen models with direct-provider models in the same config.
+## Zen vs. OpenCode Go
+
+> **Mental model:** Zen is a pay-as-you-go, per-token gateway across the full lineup. [OpenCode Go](https://opencode.ai/docs/go/) is a flat-rate subscription to a curated set of hosted open models.
+
+| | Zen | OpenCode Go |
+|---|---|---|
+| Billing | Per-token, pay-as-you-go | $10/month flat ($5 first month) |
+| Models | Full curated lineup (Anthropic, OpenAI, Google, open models, …) | Hosted open models |
+| Limits | Your balance / workspace caps | $12 per 5 hours, $30/week, $60/month equivalent |
+| After limits | — | Falls back to your Zen balance |
+
+Reach for Go when you want a predictable monthly bill on open models; reach for Zen when you want per-token access to everything. Details: [opencode.ai/docs/go](https://opencode.ai/docs/go/).
+
## Setup
```bash
@@ -39,7 +52,7 @@ In `opencode.json`, reference a Zen model with the `opencode/` prefix:
```json
{
"$schema": "https://opencode.ai/config.json",
- "model": "opencode/claude-sonnet-4-6"
+ "model": "opencode/claude-sonnet-5"
}
```
@@ -47,17 +60,18 @@ In `opencode.json`, reference a Zen model with the `opencode/` prefix:
## Available models
-Selected lineup below. **For the full list (50+ entries, latest pricing, cached-read/write rates, and endpoint URLs), see [opencode.ai/docs/zen](https://opencode.ai/docs/zen).**
+Selected lineup below. **For the full lineup (latest pricing, cached-read/write rates, and endpoint URLs), see [opencode.ai/docs/zen](https://opencode.ai/docs/zen).**
### Anthropic family
| Model ID | Input / Output (per MTok) | Notes |
|---|---|---|
-| `opencode/claude-opus-4-8` | $5 / $25 | Flagship reasoning — complex refactors, multi-file work |
-| `opencode/claude-sonnet-4-6` | $3 / $15 | Workhorse — most coding work lives here |
+| `opencode/claude-fable-5` | $10 / $50 | New flagship — hardest reasoning, complex refactors |
+| `opencode/claude-opus-4-8` | $5 / $25 | Previous flagship — still strong on multi-file work |
+| `opencode/claude-sonnet-5` | $2 / $10 | Balanced workhorse — cheaper *and* newer than Sonnet 4.6; adaptive thinking since v1.17.12 |
| `opencode/claude-haiku-4-5` | $1 / $5 | Cheap, fast — title generation, simple Q&A |
-Older versions (`claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-opus-4-1`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-3-5-haiku`) are also available — see the full list.
+Older versions (`claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-sonnet-4-6`, `claude-sonnet-4-5`) are also available — see the full list.
### OpenAI family
@@ -67,11 +81,14 @@ Older versions (`claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude
| `opencode/gpt-5.5` *(>272K)* | $10 / $45 | Same model, beyond-window pricing |
| `opencode/gpt-5.5-pro` | $30 / $180 | Pro variant |
| `opencode/gpt-5.4` *(≤272K)* | $2.50 / $15 | Mid-tier frontier |
+| `opencode/gpt-5.4` *(>272K)* | $5 / $22.50 | Same model, beyond-window pricing |
+| `opencode/gpt-5.4-pro` | $30 / $180 | Pro variant of 5.4 |
| `opencode/gpt-5.4-mini` | $0.75 / $4.50 | Cost-efficient frontier |
| `opencode/gpt-5.4-nano` | $0.20 / $1.25 | Cheap, fast, narrow tasks |
-| `opencode/gpt-5.3-codex` · `opencode/gpt-5.2-codex` | $1.75 / $14 | Codex-tuned variants |
+| `opencode/gpt-5.3-codex` | $1.75 / $14 | Codex-tuned variant |
+| `opencode/gpt-5.2` | $1.75 / $14 | Base 5.2 |
-GPT 5.1 / 5 / 5-codex / 5-nano are also available with their own pricing.
+GPT 5.1 / 5, `gpt-5.3-codex-spark`, and the `gpt-5.1-codex` family (+max, +mini) are also available — see the [live list](https://opencode.ai/docs/zen) for current pricing and note the sunset dates below.
### Other
@@ -82,9 +99,14 @@ GPT 5.1 / 5 / 5-codex / 5-nano are also available with their own pricing.
| `opencode/gemini-3-flash` | $0.50 / $3 | Cheaper Gemini variant |
| `opencode/qwen3.7-max` | $2.50 / $7.50 | Qwen flagship |
| `opencode/qwen3.7-plus` | $0.40 / $1.60 | Budget-friendly heavy lifting |
+| `opencode/deepseek-v4-pro` | $1.74 / $3.48 | DeepSeek flagship |
+| `opencode/deepseek-v4-flash` | $0.14 / $0.28 | Rock-bottom pricing |
+| `opencode/kimi-k2.7-code` | $0.95 / $4 | Moonshot coding model, current |
| `opencode/kimi-k2.6` | $0.95 / $4 | Moonshot lineup |
+| `opencode/glm-5.2` | $1.40 / $4.40 | Zhipu current |
| `opencode/glm-5.1` | $1.40 / $4.40 | Zhipu lineup |
-| `opencode/minimax-m2.7` | $0.30 / $1.20 | MiniMax current |
+| `opencode/minimax-m3` | $0.30 / $1.20 | MiniMax current |
+| `opencode/minimax-m2.7` | $0.30 / $1.20 | Previous MiniMax |
| `opencode/grok-build-0.1` | $1 / $2 | xAI coding model |
### Free tier (rotating, time-limited)
@@ -94,9 +116,22 @@ For community feedback during model rollout:
- `opencode/big-pickle` *(stealth model)*
- `opencode/deepseek-v4-flash-free`
- `opencode/mimo-v2.5-free`
+- `opencode/north-mini-code-free` *(new)*
- `opencode/nemotron-3-ultra-free`
-Great for learning OpenCode without burning a budget.
+Great for learning OpenCode without burning a budget. The list rotates — a free model can disappear, become paid, or be replaced at any time; check `/models` for what's live today.
+
+### Deprecations & sunsets
+
+Deprecated Zen models keep working until their sunset date:
+
+| Model(s) | Sunset date |
+|---|---|
+| `glm-5` | 2026-05-14 *(past)* |
+| `claude-sonnet-4` | 2026-06-15 *(past)* |
+| `gpt-5.2-codex`, `gpt-5.1-codex` (+max, +mini), `gpt-5-codex` | 2026-07-23 |
+| `claude-opus-4-1` | 2026-08-05 |
+| `minimax-m2.5`, `kimi-k2.5` | 2026-08-05 |
## Billing
@@ -104,7 +139,7 @@ Great for learning OpenCode without burning a budget.
- **Workspace limits:** monthly cap for a team and per-member spending limits.
- **BYOK:** bring your own Anthropic / OpenAI keys and Zen routes those provider calls through your credentials while still letting you use other Zen-hosted models.
- **Transaction fees:** credit card fees pass through at cost (per docs: 4.4% + $0.30 per transaction).
-- **Title model:** sessions show `claude-haiku-3-5` charges — that's the low-cost model OpenCode uses to generate session titles automatically.
+- **Title model:** sessions show small charges from a low-cost small model — that's what OpenCode uses to generate session titles automatically.
## Patterns
@@ -114,12 +149,12 @@ Different agents, different models. A cheap model handles read-heavy subagents;
```json
{
- "model": "opencode/claude-sonnet-4-6",
+ "model": "opencode/claude-sonnet-5",
"agent": {
- "explore": { "model": "opencode/qwen3.6-plus" },
- "scout": { "model": "opencode/qwen3.6-plus" },
+ "explore": { "model": "opencode/qwen3.7-plus" },
+ "scout": { "model": "opencode/qwen3.7-plus" },
"plan": { "model": "opencode/claude-haiku-4-5" },
- "build": { "model": "opencode/claude-sonnet-4-6" }
+ "build": { "model": "opencode/claude-sonnet-5" }
}
}
```
@@ -132,7 +167,7 @@ For complex tasks, plan with the smartest model, then hand the atomic plan to a
{
"agent": {
"plan": { "model": "opencode/claude-opus-4-8" },
- "build": { "model": "opencode/claude-sonnet-4-6" }
+ "build": { "model": "opencode/claude-sonnet-5" }
}
}
```
@@ -143,7 +178,7 @@ Reuse Anthropic credits while still having one-key access to GPT and Gemini.
```json
{
- "model": "anthropic/claude-sonnet-4-5",
+ "model": "anthropic/claude-sonnet-5",
"provider": {
"anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } }
},
@@ -183,4 +218,4 @@ Both are gateways. Zen is **curated** — the OpenCode team picks and tunes mode
---
-*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
+*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
diff --git a/mcp-servers/README.md b/mcp-servers/README.md
index 812f276..63bd69e 100644
--- a/mcp-servers/README.md
+++ b/mcp-servers/README.md
@@ -23,24 +23,7 @@ If everything you need is already in local files, you probably don't need MCP ye
## Cost of adding a server
-MCP tools land in the model's tool surface every turn. A heavy server (say, a full GitHub integration with 40 tools) can eat 10K+ tokens of context **just to describe the available tools**. Don't add a server you won't use, and disable tools you don't need with the `tools` map:
-
-```json
-{
- "tools": {
- "github_*": false,
- "slack_*": false
- },
- "agent": {
- "issue-triager": {
- "tools": {
- "github_get_issue": true,
- "github_list_issues": true
- }
- }
- }
-}
-```
+Every server's tool descriptions land in the model's context on every turn — a heavy server can cost thousands of tokens before you call anything. See the [token budget warning in `docs/mcp.md`](../docs/mcp.md#token-budget-warning) for the details and the `tools`-map pattern for disabling tools you don't need.
## Discovery
@@ -58,7 +41,7 @@ For new servers, also worth checking:
| Server won't connect | `opencode mcp debug ` |
| OAuth flow stuck | `opencode mcp logout ` then `opencode mcp auth ` |
| Tools missing in the model surface | Check the `tools` map and the agent's `tools` override |
-| Local server fails on Windows | Make sure the `command` array uses npx with `-y`, and that Node 18+ is on PATH |
+| Local server fails on Windows | Make sure the `command` array uses npx with `-y`, and that Node 20+ (current LTS) is on PATH |
| Timeouts | Bump `timeout` (default 5000ms) under the server's config |
> 📚 Full MCP guide in OpenCode: [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers).
diff --git a/mcp-servers/context7.md b/mcp-servers/context7.md
index 3602d10..550e969 100644
--- a/mcp-servers/context7.md
+++ b/mcp-servers/context7.md
@@ -15,9 +15,9 @@ LLMs hallucinate APIs that don't exist or use APIs that were deprecated three ve
## Setup
-Get an API key at [context7.com](https://context7.com).
+An API key is optional — the server works without one, but signing up at [context7.com](https://context7.com) for a free key is recommended for higher rate limits.
-Add to `opencode.json`:
+Add to `opencode.json` (drop the `headers` block if you're going keyless):
```json
{
@@ -34,7 +34,7 @@ Add to `opencode.json`:
}
```
-Set the env var in your shell:
+If you use a key, set the env var in your shell:
```bash
export CONTEXT7_API_KEY=ctx7_...
@@ -54,7 +54,7 @@ specifically how to handle redirects from a loader
```
```text
-I'm migrating from Next.js 14 to 15. Use context7 to find the breaking
+I'm migrating from Next.js 15 to 16. Use context7 to find the breaking
changes in the App Router and surface the ones that affect our project.
```
@@ -86,7 +86,7 @@ Thousands of libraries — React, Next.js, Vue, Angular, Svelte, Tailwind, TanSt
## Gotchas
-- **API key required** — there's a free tier, but you need to sign up.
+- **Rate limits without a key** — the keyless endpoint works but is rate-limited more aggressively. A free API key raises the limits.
- **Token budget** — Context7 returns chunks of docs; very chatty queries can push past your context window. Be specific in what you ask for.
- **Version drift** — pin the version explicitly when your repo's `package.json` is behind latest.
diff --git a/mcp-servers/grep.md b/mcp-servers/grep.md
index 3201a25..3a21320 100644
--- a/mcp-servers/grep.md
+++ b/mcp-servers/grep.md
@@ -90,4 +90,6 @@ patterns they share. Skip the "hello world" projects.
## Resources
- [grep.app](https://grep.app/) — same backing service, web UI
-- [Vercel's announcement](https://vercel.com/blog/) — official Vercel posts about Grep
+- [Vercel's announcement](https://vercel.com/blog/grep-a-million-github-repositories-via-mcp) — Grep MCP launch post
+
+> ⚠️ **Warning:** `mcp.grep.app` was intermittently unreachable when last checked (2026-07-05). If `opencode mcp list` shows the server failing to connect, that may be why — try again later.
diff --git a/mcp-servers/playwright.md b/mcp-servers/playwright.md
index ca02720..a851441 100644
--- a/mcp-servers/playwright.md
+++ b/mcp-servers/playwright.md
@@ -19,11 +19,8 @@ Add to `opencode.json`:
"mcp": {
"playwright": {
"type": "local",
- "command": ["npx", "-y", "@playwright/mcp@latest"],
- "enabled": true,
- "environment": {
- "BROWSER_TYPE": "chromium"
- }
+ "command": ["npx", "-y", "@playwright/mcp@latest", "--browser", "chromium"],
+ "enabled": true
}
}
}
@@ -37,6 +34,8 @@ opencode mcp list
You should see `playwright` in the list.
+> 💡 **Pro Tip:** The browser is picked with the `--browser` CLI flag (`chromium`, `firefox`, `webkit`, `msedge`) or the `PLAYWRIGHT_MCP_BROWSER` env var — there is no `BROWSER_TYPE` variable.
+
## Example prompts
```text
@@ -81,14 +80,14 @@ Two-three iteration rounds usually closes the gap.
## What it won't do
-- Persist browser state across sessions by default (use `--user-data-dir` if you need this)
- Bypass strong bot detection (Cloudflare, etc.)
- Replace a real E2E test suite (use the screenshots and traces to *write* the tests)
## Gotchas
- **First run is slow** — Playwright downloads a browser the first time you invoke it.
-- **Headless by default** — you don't see the browser. Pass `BROWSER_HEADED=1` in `environment` to watch it run (useful for debugging).
+- **Headed by default** — when a display is available, a visible browser window opens. Pass `--headless` (or set `PLAYWRIGHT_MCP_HEADLESS=1`) for CI and other display-less environments.
+- **Persistent profile by default** — cookies and logins survive across sessions. Pass `--isolated` for a throwaway in-memory session instead.
- **Cross-origin / authenticated flows** — use Playwright's auth-state file pattern; see the upstream docs.
## Resources
diff --git a/opencode.json b/opencode.json
index 45cd4f9..a05f349 100644
--- a/opencode.json
+++ b/opencode.json
@@ -1,6 +1,6 @@
{
"$schema": "https://opencode.ai/config.json",
- "model": "anthropic/claude-sonnet-4-5",
+ "model": "anthropic/claude-sonnet-5",
"share": "manual",
"autoupdate": "notify",
"instructions": ["AGENTS.md", "CONTRIBUTING.md"],
@@ -34,7 +34,7 @@
},
"agent": {
"build": {
- "model": "anthropic/claude-sonnet-4-5"
+ "model": "anthropic/claude-sonnet-5"
},
"plan": {
"model": "anthropic/claude-haiku-4-5"
diff --git a/specialized-agents/README.md b/specialized-agents/README.md
index ea9fd38..a38b908 100644
--- a/specialized-agents/README.md
+++ b/specialized-agents/README.md
@@ -28,7 +28,7 @@ You can also reference the prompt file from `opencode.json` without copying:
"code-reviewer": {
"description": "Senior code reviewer",
"mode": "subagent",
- "model": "anthropic/claude-sonnet-4-5",
+ "model": "anthropic/claude-sonnet-5",
"prompt": "{file:./specialized-agents/system-prompts/code-reviewer-prompt.md}",
"permission": { "edit": "deny" }
}
@@ -36,17 +36,19 @@ You can also reference the prompt file from `opencode.json` without copying:
}
```
+> ⚠️ **Warning:** `{file:...}` inlines the file verbatim — including its YAML frontmatter — into the system prompt. Strip the frontmatter block from the copy you reference this way.
+
## Available roles
| Role | Mode | Reach for it when… | Prompt | Description |
|---|---|---|---|---|
| **Code Reviewer** | subagent | Surface bugs / security / perf / maintainability in a diff or branch | [prompt](system-prompts/code-reviewer-prompt.md) | [description](descriptions/code-reviewer.md) |
| **Security Reviewer** | subagent | Audit code for OWASP-style vulnerabilities | [prompt](system-prompts/security-reviewer-prompt.md) | [description](descriptions/security-reviewer.md) |
-| **Backend Engineer** | primary | TypeScript/Go/Python API work, DB integration, REST/GraphQL | [prompt](system-prompts/backend-engineer-prompt.md) | [description](descriptions/backend-engineer.md) |
-| **Frontend Engineer** | primary | React/Tailwind/TypeScript UI work, accessibility, component design | [prompt](system-prompts/frontend-engineer-prompt.md) | [description](descriptions/frontend-engineer.md) |
-| **Tech Lead** | primary | Architectural decisions, cross-team trade-offs, sequencing work | [prompt](system-prompts/tech-lead-prompt.md) | [description](descriptions/tech-lead.md) |
-| **UX Engineer** | primary | Component-first UI work, design-system alignment | [prompt](system-prompts/ux-engineer-prompt.md) | [description](descriptions/ux-engineer.md) |
-| **Database Engineer** | primary | Schema design, migrations, query performance | [prompt](system-prompts/database-engineer-prompt.md) | [description](descriptions/database-engineer.md) |
+| **Backend Engineer** | all (primary + subagent) | TypeScript/Go/Python API work, DB integration, REST/GraphQL | [prompt](system-prompts/backend-engineer-prompt.md) | [description](descriptions/backend-engineer.md) |
+| **Frontend Engineer** | all (primary + subagent) | React/Tailwind/TypeScript UI work, accessibility, component design | [prompt](system-prompts/frontend-engineer-prompt.md) | [description](descriptions/frontend-engineer.md) |
+| **Tech Lead** | all (primary + subagent) | Architectural decisions, cross-team trade-offs, sequencing work | [prompt](system-prompts/tech-lead-prompt.md) | [description](descriptions/tech-lead.md) |
+| **UX Engineer** | all (primary + subagent) | Component-first UI work, design-system alignment | [prompt](system-prompts/ux-engineer-prompt.md) | [description](descriptions/ux-engineer.md) |
+| **Database Engineer** | all (primary + subagent) | Schema design, migrations, query performance | [prompt](system-prompts/database-engineer-prompt.md) | [description](descriptions/database-engineer.md) |
> 💡 These are starting points. Edit the prompts to match your stack — replace generic guidance with your actual conventions, technologies, and naming.
@@ -57,7 +59,7 @@ You can also reference the prompt file from `opencode.json` without copying:
```text
[build] > implement the OAuth refresh endpoint
[build] > @code-reviewer review the changes
-[build] > @security-reviewer audit the same files
+[build] > @security-auditor audit the same files
[build] > address the high-severity findings
```
diff --git a/specialized-agents/system-prompts/backend-engineer-prompt.md b/specialized-agents/system-prompts/backend-engineer-prompt.md
index 701b95a..32c2466 100644
--- a/specialized-agents/system-prompts/backend-engineer-prompt.md
+++ b/specialized-agents/system-prompts/backend-engineer-prompt.md
@@ -1,7 +1,7 @@
---
description: Senior backend engineer — TypeScript/Go/Python, APIs, databases, distributed systems. Implements features end-to-end with tests.
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.2
permission:
edit: allow
diff --git a/specialized-agents/system-prompts/code-reviewer-prompt.md b/specialized-agents/system-prompts/code-reviewer-prompt.md
index 1424c2e..59ad464 100644
--- a/specialized-agents/system-prompts/code-reviewer-prompt.md
+++ b/specialized-agents/system-prompts/code-reviewer-prompt.md
@@ -1,7 +1,7 @@
---
description: Senior code reviewer — reads diffs and surfaces bugs, security issues, perf problems, and maintainability concerns without modifying files.
mode: subagent
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.1
permission:
edit: deny
diff --git a/specialized-agents/system-prompts/database-engineer-prompt.md b/specialized-agents/system-prompts/database-engineer-prompt.md
index 167ae6c..2f54fd0 100644
--- a/specialized-agents/system-prompts/database-engineer-prompt.md
+++ b/specialized-agents/system-prompts/database-engineer-prompt.md
@@ -1,7 +1,7 @@
---
description: Database engineer — schema design, migrations, indexing, and query performance. Postgres-first but adapts.
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.1
permission:
edit: allow
diff --git a/specialized-agents/system-prompts/frontend-engineer-prompt.md b/specialized-agents/system-prompts/frontend-engineer-prompt.md
index 1e2d3a8..d8191ed 100644
--- a/specialized-agents/system-prompts/frontend-engineer-prompt.md
+++ b/specialized-agents/system-prompts/frontend-engineer-prompt.md
@@ -1,7 +1,7 @@
---
description: Senior frontend engineer — React, TypeScript, Tailwind. Component-first, accessibility-aware, tests visual behavior with Vitest + Testing Library.
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.2
permission:
edit: allow
diff --git a/specialized-agents/system-prompts/security-reviewer-prompt.md b/specialized-agents/system-prompts/security-reviewer-prompt.md
index 14e24e7..6fd395e 100644
--- a/specialized-agents/system-prompts/security-reviewer-prompt.md
+++ b/specialized-agents/system-prompts/security-reviewer-prompt.md
@@ -1,7 +1,7 @@
---
description: Security-focused reviewer — audits code for vulnerabilities (OWASP Top 10, secret leaks, auth/authz issues) and reports findings without modifying files.
mode: subagent
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.1
permission:
edit: deny
diff --git a/specialized-agents/system-prompts/ux-engineer-prompt.md b/specialized-agents/system-prompts/ux-engineer-prompt.md
index 63d895a..58bcc3a 100644
--- a/specialized-agents/system-prompts/ux-engineer-prompt.md
+++ b/specialized-agents/system-prompts/ux-engineer-prompt.md
@@ -1,7 +1,7 @@
---
description: UX engineer — bridges design and code. Builds design-system primitives, ensures component-level consistency, prototypes interactions.
mode: all
-model: anthropic/claude-sonnet-4-5
+model: anthropic/claude-sonnet-5
temperature: 0.2
permission:
edit: allow
+
# OpenCode: Everything You Need to Know
-A practical guide to [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Built around clear mental models and real examples, not marketing.
+The community field guide to [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Clear mental models, real examples, every fact verified against the current release.
[](LICENSE)
-[](https://github.com/anomalyco/opencode/releases)
-[](#updates--deprecations)
+[](https://github.com/anomalyco/opencode/releases)
+[](#updates--deprecations)
[](CONTRIBUTING.md)
+[](https://github.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/stargazers)
```bash
curl -fsSL https://opencode.ai/install | bash
@@ -15,6 +18,8 @@ curl -fsSL https://opencode.ai/install | bash
> ⚖️ **Not affiliated with the OpenCode team.** This is a community-maintained guide. For canonical sources, check [opencode.ai/docs](https://opencode.ai/docs/) and [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode).
+> 💡 **Pro Tip:** If this guide saves you an afternoon, a ⭐ helps other developers find it.
+
---
## 🧭 Choose your path
@@ -44,7 +49,7 @@ curl -fsSL https://opencode.ai/install | bash
### What is OpenCode?
-OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by [Anomaly](https://github.com/anomalyco), MIT-licensed.
+OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by [Anomaly](https://github.com/anomalyco), MIT-licensed — and as of July 2026 the [most-starred coding agent on GitHub](https://github.com/anomalyco/opencode) (182K+ stars), with [8M monthly users by the founder's count](https://betakit.com/qa-opencodes-founder-on-how-the-ai-agent-went-from-zero-to-8-million-users-in-a-year/).
**Three things it does that a chat UI can't:**
@@ -66,7 +71,7 @@ opencode run "fix the failing test in src/api.test.ts"
opencode serve --port 4096 # headless server
```
-> OpenCode sits in the same space as Claude Code, Cursor, and Aider — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow.
+> OpenCode sits in the same space as Claude Code, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was [retired in June](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)
> ⚠️ **AI-coding caveat:** OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. **You're still the reviewer.** Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.
@@ -76,7 +81,7 @@ opencode serve --port 4096 # headless server
| Limitation | Detail |
|---|---|
-| **No inline editor completion** | OpenCode is a conversational agent, not Copilot-style autocomplete. For ghost-text-while-you-type, reach for [Copilot](https://github.com/features/copilot), [Cursor Tab](https://cursor.sh/), [Codeium](https://codeium.com/), or [Supermaven](https://supermaven.com/) — or alongside. |
+| **No inline editor completion** | OpenCode is a conversational agent, not Copilot-style autocomplete. For ghost-text-while-you-type, reach for [Copilot](https://github.com/features/copilot), [Cursor Tab](https://cursor.com/), [Windsurf (formerly Codeium)](https://windsurf.com/), or [Supermaven](https://supermaven.com/) — or alongside. |
| **Quality depends on the underlying model** | OpenCode doesn't replace the LLM's reasoning. If your task fails on Sonnet, switching to OpenCode won't fix it. |
| **Provider-agnostic ≠ provider-equivalent** | Some models tool-call better than others. A slug swap isn't free. |
| **TUI on slow SSH / minimal terminals** | The TUI uses truecolor and complex layouts. Degrades over slow connections. `opencode serve` + `attach` or `opencode run` are better for those cases. |
@@ -87,10 +92,10 @@ opencode serve --port 4096 # headless server
**When something else fits better:**
-- Want a polished single-vendor product → **Claude Code** or **Cursor**.
+- Want a polished single-vendor product → **Claude Code** or **Codex CLI**.
- Deeply embedded in VS Code workflow → **Cursor** or **GitHub Copilot**.
-- Want a small Python tool you can read end-to-end → **[Aider](https://aider.chat/)**.
-- Don't want to manage provider keys → a managed hosted product.
+- Want a small Python tool you can read end-to-end → **[Aider](https://aider.chat/)** (note: development has slowed markedly in 2026).
+- Don't want to manage provider keys → a managed hosted product, or [OpenCode Go](#opencode-go).
> OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.
@@ -115,8 +120,8 @@ scoop install opencode # Windows
choco install opencode # Windows
sudo pacman -S opencode # Arch
paru -S opencode-bin # Arch (AUR)
-mise use -g github:anomalyco/opencode # mise users
-nix run nixpkgs#opencode # Nix
+mise use -g github:anomalyco/opencode # mise users
+docker run -it --rm ghcr.io/anomalyco/opencode # Docker
```
A desktop app for macOS / Windows / Linux is in beta at [opencode.ai/download](https://opencode.ai/download).
@@ -170,22 +175,25 @@ This repo's own [`.opencode/`](.opencode/) directory is a working example:
### Models & Providers
-OpenCode is **provider-agnostic**. Three ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:
+OpenCode is **provider-agnostic**. Four ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:
| | Best for | Trade-off |
|---|---|---|
| **Direct providers** (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure) | You already have credits with a provider | Manage one key per provider |
| **[OpenCode Zen](#opencode-zen)** — pay-as-you-go gateway | One key, curated lineup, no commitment | Pricier per token than going direct in some cases |
+| **[OpenCode Go](#opencode-go)** — flat-rate subscription | Predictable $10/month, zero key management | Curated open models only, usage limits |
| **Local models** (Ollama, LM Studio, llama.cpp) | Offline, strict data-residency, hobbyist | Quality varies hugely with model and hardware |
There's no universally right answer — pick what fits.
+> ⚠️ **Warning:** You can no longer sign in with a Claude Pro/Max subscription. OpenCode removed its built-in Anthropic OAuth login in March 2026 at Anthropic's legal request ([PR #18186](https://github.com/anomalyco/opencode/pull/18186)). Anthropic models still work fine — via an **API key** in the provider config below, or via **Zen**.
+
#### Direct provider config
```json
{
"$schema": "https://opencode.ai/config.json",
- "model": "anthropic/claude-sonnet-4-5",
+ "model": "anthropic/claude-sonnet-5",
"provider": {
"anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } },
"openai": { "options": { "apiKey": "{file:~/.secrets/openai-key}" } }
@@ -201,7 +209,7 @@ Per-agent model override:
{
"agent": {
"plan": { "model": "anthropic/claude-haiku-4-5" },
- "deep-thinker": { "model": "openai/gpt-5", "options": { "reasoningEffort": "high" } }
+ "deep-thinker": { "model": "openai/gpt-5.5", "options": { "reasoningEffort": "high" } }
}
}
```
@@ -217,23 +225,30 @@ A curated, pay-as-you-go AI gateway. The OpenCode team tests and tunes models fo
/models # browse the lineup
```
-**Pricing snapshot** *(verified 2026-06-08; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
+**Pricing snapshot** *(verified 2026-07-05; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
| Model ID | Input / Output (per MTok) | Reach for it when… |
|---|---|---|
+| `opencode/claude-fable-5` | $10 / $50 | Absolute frontier — the hardest reasoning problems |
| `opencode/claude-opus-4-8` | $5 / $25 | Flagship reasoning — complex refactors, large multi-file work |
-| `opencode/claude-sonnet-4-6` | $3 / $15 | Balanced everyday coding |
+| `opencode/claude-sonnet-5` | $2 / $10 | Balanced everyday coding — newer *and* cheaper than Sonnet 4.6 |
| `opencode/claude-haiku-4-5` | $1 / $5 | Fast, lightweight tasks |
| `opencode/gpt-5.5` *(≤272K)* | $5 / $30 | Long-context, OpenAI ecosystem |
| `opencode/gpt-5.4-mini` | $0.75 / $4.50 | Cost-efficient frontier |
-| `opencode/gemini-3.1-pro` | $2 / $12 | Multimodal, Google ecosystem |
+| `opencode/gemini-3.1-pro` *(≤200K)* | $2 / $12 | Multimodal, Google ecosystem |
| `opencode/qwen3.7-plus` | $0.40 / $1.60 | Budget-friendly heavy lifting |
-**Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `nemotron-3-ultra-free`.
+**Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `north-mini-code-free`, `nemotron-3-ultra-free`.
+
+> 📚 Full lineup, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, DeepSeek, Grok, and the Claude Opus 4.8/4.7/4.6/4.5 line: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide (incl. deprecation sunset dates): [`docs/zen.md`](docs/zen.md).
-> 50+ models total — full list, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, Grok, and the Claude Opus 4.8/4.7/4.5/4.1 line: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide: [`docs/zen.md`](docs/zen.md).
+> 💡 **Pattern: cheap explorer / strong executor.** Use a cheap model (`qwen3.7-plus`, `gpt-5.4-mini`) for `explore` and `scout` subagents that read a lot, and a stronger one (`claude-sonnet-5` or `claude-opus-4-8`) for the main `build` agent that does the editing.
-> 💡 **Pattern: cheap explorer / strong executor.** Use a cheap model (`qwen3.7-plus`, `gpt-5.4-mini`) for `explore` and `scout` subagents that read a lot, and a stronger one (`claude-sonnet-4-6` or `claude-opus-4-8`) for the main `build` agent that does the editing.
+#### OpenCode Go
+
+The flat-rate alternative to Zen: **$10/month ($5 your first month)** for a curated set of hosted open coding models — no API keys, no per-token math. Usage limits apply (roughly $12 per 5 hours / $30 per week / $60 per month of equivalent usage); past them, Go can fall back to a Zen balance.
+
+**Zen vs. Go in one line:** Zen bills per token across the full lineup; Go is a fixed subscription to open models. Reach for Go to learn and hack on a predictable budget; reach for Zen (or direct keys) when you want frontier models. Details: [opencode.ai/docs/go](https://opencode.ai/docs/go/) · [`docs/zen.md`](docs/zen.md).
---
@@ -262,7 +277,7 @@ Natural workflow:
(implements, edits, runs tests)
```
-> 💡 Prompts like `think hard`, `think more`, or `ultrathink` nudge reasoning depth on supported models — the same pattern in the [Anthropic prompt engineering guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview).
+> 💡 Prompts like `think hard`, `think more`, or `ultrathink` nudge reasoning depth on supported models — the same pattern in the [Anthropic prompt engineering guide](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/overview).
#### File references and shell
@@ -362,7 +377,7 @@ opencode github install # add a workflow file to your repo
opencode pr 123 # check out PR #123 and start a session
```
-Useful `run` flags: `--continue` / `--session