Merge pull request #5 from wesammustafa/docs/opencode-v1.17-rebrand

This commit is contained in:
Wesam Abousaid
2026-07-05 14:22:47 +02:00
committed by GitHub
47 changed files with 427 additions and 202 deletions
+1 -1
View File
@@ -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.
+2 -2
View File
@@ -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
+1
View File
@@ -8,6 +8,7 @@
"MD026": { "punctuation": ".,;:" },
"MD028": false,
"MD029": false,
"MD060": false,
"MD033": false,
"MD036": false,
"MD040": false,
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+3 -3
View File
@@ -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:`, …)
+1 -1
View File
@@ -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):
+2 -4
View File
@@ -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.
+1 -1
View File
@@ -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
-2
View File
@@ -31,5 +31,3 @@ export const AuditLog = async ({ directory }) => {
},
};
};
export default AuditLog;
+1 -3
View File
@@ -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;
+15 -8
View File
@@ -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
+1 -1
View File
@@ -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.
+13 -8
View File
@@ -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.
---
+2
View File
@@ -12,6 +12,8 @@ Diagrams, screenshots, and visual assets for this guide.
![Alt text describing the image](Images/your-image.svg)
```
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.
+74
View File
@@ -0,0 +1,74 @@
<svg width="1280" height="640" viewBox="0 0 1280 640" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OpenCode: Everything You Need to Know — the community field guide to the open-source AI coding agent">
<defs>
<radialGradient id="glow" cx="22%" cy="18%" r="85%">
<stop offset="0%" stop-color="#1c1330"/>
<stop offset="55%" stop-color="#0e0d14"/>
<stop offset="100%" stop-color="#0a0a0e"/>
</radialGradient>
<linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
<stop offset="0%" stop-color="#8b5cf6"/>
<stop offset="100%" stop-color="#c4b5fd"/>
</linearGradient>
<linearGradient id="cardstroke" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#3f3358"/>
<stop offset="100%" stop-color="#1d1a26"/>
</linearGradient>
</defs>
<rect width="1280" height="640" fill="url(#glow)"/>
<!-- faint grid -->
<g stroke="#ffffff" stroke-opacity="0.025">
<path d="M0 160H1280M0 320H1280M0 480H1280"/>
<path d="M256 0V640M512 0V640M768 0V640M1024 0V640"/>
</g>
<!-- left: wordmark block -->
<g font-family="ui-sans-serif, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif">
<text x="96" y="178" font-size="17" font-weight="600" letter-spacing="6" fill="#a78bfa">THE COMMUNITY FIELD GUIDE</text>
<text x="93" y="272" font-size="92" font-weight="800" fill="#f5f3ff" letter-spacing="-2">OpenCode</text>
<text x="96" y="330" font-size="34" font-weight="500" fill="#b9b4c7">Everything You Need to Know</text>
<rect x="96" y="366" width="72" height="4" rx="2" fill="url(#accent)"/>
<text x="96" y="416" font-size="21" fill="#8f8a9e">From first prompt to agents, skills, plugins, MCP,</text>
<text x="96" y="448" font-size="21" fill="#8f8a9e">and headless CI — verified against every release.</text>
<!-- chips -->
<g font-size="15" font-weight="600">
<rect x="96" y="490" width="92" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="142" y="513" fill="#c4b5fd" text-anchor="middle">Agents</text>
<rect x="200" y="490" width="80" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="240" y="513" fill="#c4b5fd" text-anchor="middle">Skills</text>
<rect x="292" y="490" width="96" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="340" y="513" fill="#c4b5fd" text-anchor="middle">Plugins</text>
<rect x="400" y="490" width="72" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="436" y="513" fill="#c4b5fd" text-anchor="middle">MCP</text>
<rect x="484" y="490" width="70" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="519" y="513" fill="#c4b5fd" text-anchor="middle">Zen</text>
<rect x="566" y="490" width="122" height="36" rx="18" fill="#171423" stroke="#332b49"/>
<text x="627" y="513" fill="#c4b5fd" text-anchor="middle">Headless CI</text>
</g>
</g>
<!-- right: terminal card -->
<g>
<rect x="742" y="150" width="446" height="312" rx="16" fill="#100e17" stroke="url(#cardstroke)" stroke-width="1.5"/>
<rect x="742" y="150" width="446" height="44" rx="16" fill="#161320"/>
<rect x="742" y="178" width="446" height="16" fill="#161320"/>
<circle cx="772" cy="172" r="6" fill="#ff5f57"/>
<circle cx="794" cy="172" r="6" fill="#febc2e"/>
<circle cx="816" cy="172" r="6" fill="#28c840"/>
<text x="965" y="178" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14" fill="#6f697f" text-anchor="middle">~/your-project</text>
<g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16.5">
<text x="774" y="238"><tspan fill="#8b5cf6">$</tspan><tspan fill="#e8e6ef" dx="10">curl -fsSL opencode.ai/install | bash</tspan></text>
<text x="774" y="274"><tspan fill="#8b5cf6">$</tspan><tspan fill="#e8e6ef" dx="10">opencode</tspan></text>
<text x="774" y="318" fill="#6f697f">┌ opencode v1.17</text>
<text x="774" y="350"><tspan fill="#6f697f">│</tspan><tspan fill="#b9b4c7" dx="10">agent</tspan><tspan fill="#c4b5fd" dx="12">build</tspan><tspan fill="#6f697f" dx="12">· Tab to cycle</tspan></text>
<text x="774" y="382"><tspan fill="#6f697f">│</tspan><tspan fill="#b9b4c7" dx="10">model</tspan><tspan fill="#c4b5fd" dx="12">any provider, your keys</tspan></text>
<text x="774" y="414" fill="#6f697f">└ /init to generate AGENTS.md</text>
<text x="774" y="446"><tspan fill="#8b5cf6">&gt;</tspan><tspan fill="#e8e6ef" dx="10">fix the failing test</tspan><tspan fill="#c4b5fd" dx="6">▌</tspan></text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 266 KiB

+58 -40
View File
@@ -1,11 +1,14 @@
<img src="Images/banner.svg" alt="OpenCode: Everything You Need to Know — the community field guide to the open-source AI coding agent" width="100%">
# 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: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
[![OpenCode v1.16.2](https://img.shields.io/badge/OpenCode-v1.16.2-7C3AED?style=flat-square)](https://github.com/anomalyco/opencode/releases)
[![Last reviewed](https://img.shields.io/badge/last%20reviewed-June%202026-22c55e?style=flat-square)](#updates--deprecations)
[![OpenCode v1.17.13](https://img.shields.io/badge/OpenCode-v1.17.13-7C3AED?style=flat-square)](https://github.com/anomalyco/opencode/releases)
[![Last reviewed](https://img.shields.io/badge/last%20reviewed-July%202026-22c55e?style=flat-square)](#updates--deprecations)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4?style=flat-square)](CONTRIBUTING.md)
[![GitHub stars](https://img.shields.io/github/stars/wesammustafa/OpenCode-Everything-You-Need-to-Know?style=flat-square&color=eab308)](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`.
> 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).
> 📚 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).
> 💡 **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.
> 💡 **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.
#### 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 <id>` (resume), `--fork` (branch a session), `--share` (publish), `--format json` (machine-readable), `--file <path>` (attach), `--replay` (interactive replay, v1.16+), `--dangerously-skip-permissions` (auto-approve everything not `deny` — **CI only**).
Useful `run` flags: `--continue` / `--session <id>` (resume), `--fork` (branch a session), `--share` (publish), `--format json` (machine-readable), `--file <path>` (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 |
| `@<path>` | File content (fuzzy resolved) |
| `` `!<cmd>` `` | Shell stdout |
| ``!`<cmd>` `` | 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.**
+1 -1
View File
@@ -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.
+8 -4
View File
@@ -25,13 +25,13 @@ Two locations, same format:
| Project | `.opencode/agents/<name>.md` |
| Global | `~/.config/opencode/agents/<name>.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/<name>.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).*
+16 -8
View File
@@ -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 `/<name>` | **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) |
| `@<path>` | File content (fuzzy resolved) |
| `` `!<cmd>` `` | Shell stdout |
| ``!`<cmd>` `` | 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).*
+26 -6
View File
@@ -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).*
+9 -5
View File
@@ -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/<name>.md` | `.opencode/commands/<name>.md` |
| `.claude/skills/<name>/SKILL.md` | `.opencode/skills/<name>/SKILL.md` *(but also reads from `.claude/skills/`)* |
| `.claude/settings.json` hooks (Python scripts on lifecycle events) | `.opencode/plugins/<name>.{js,ts}` (JS/TS modules on events) |
| `.claude/settings.json` hooks (shell commands on lifecycle events) | `.opencode/plugins/<name>.{js,ts}` (JS/TS modules on events) |
| `.claude/agents/<name>.md` | `.opencode/agents/<name>.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/).*
+9 -1
View File
@@ -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).*
+9 -5
View File
@@ -77,26 +77,30 @@ Two character prefixes that change how you talk to OpenCode in prompts:
| Prefix | Purpose | Example |
|---|---|---|
| `@<path>` | Attach a file's content (fuzzy resolved) | `look at @src/api/auth.ts` |
| `!<cmd>` | Run shell, inject output | `!git diff` then ask Claude about it |
| `!<cmd>` | Run shell, inject output | `!git diff` then ask the model about it |
## What next?
- **[Custom Commands](commands.md)** — turn prompts into `/<name>` 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/).*
+19 -3
View File
@@ -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/).*
+7 -2
View File
@@ -41,6 +41,7 @@ opencode [project] [flags]
| `--port`, `--hostname` | Bind the underlying server |
| `--mdns`, `--mdns-domain` | mDNS discovery |
| `--cors <origins>` | 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 <n>` | How much recent history to show when replaying |
| `--command <name>` | 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).*
+23 -10
View File
@@ -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/).*
+5 -5
View File
@@ -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/).*
+9 -2
View File
@@ -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.*
+4
View File
@@ -56,3 +56,7 @@
Any markdown file in `.opencode/commands/<name>.md` (or `~/.config/opencode/commands/`) creates a `/<name>` 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.*
+8 -4
View File
@@ -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 `/<name>` |
| File | `.opencode/skills/<name>/SKILL.md` *(folder)* | `.opencode/commands/<name>.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/<name>/SKILL.md` | Global — Claude Code compatibility |
| `~/.agents/skills/<name>/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).*
+7 -1
View File
@@ -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.*
+4 -4
View File
@@ -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 <number>` 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/).*
+53 -18
View File
@@ -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/).*
+2 -19
View File
@@ -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 <name>` |
| OAuth flow stuck | `opencode mcp logout <name>` then `opencode mcp auth <name>` |
| 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).
+5 -5
View File
@@ -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.
+3 -1
View File
@@ -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.
+6 -7
View File
@@ -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
+2 -2
View File
@@ -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"
+9 -7
View File
@@ -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
```
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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