mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified against opencode.ai/docs and github.com/anomalyco/opencode. Correctness fixes: - Plugins: tool.execute.before/after and shell.env are top-level hooks with an (input, output) signature, not event.type values. Rewrite both shipped example plugins plus the docs/migration examples so they fire. - Permissions: bash glob maps resolve last-matching-rule-wins (catch-all "*" first), not most-specific-wins. Fix prose, reorder examples, and fix the shipped opencode.json (rm -rf* deny was shadowed by a later rm *). - Drop non-existent permission keys repo_clone/repo_overview (15 keys, not 17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort into model options; fix the `mise` install command. Currency updates: - v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section. - Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4, gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs). - Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and native GitHub commands; correct the specialist-prompt count; bump dates. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 4.8
parent
99e6c6b2a1
commit
29a69a35b0
@@ -5,7 +5,7 @@ Working examples of OpenCode plugins. Drop-in to any project — pure JS, no npm
|
||||
| Plugin | What it does |
|
||||
|---|---|
|
||||
| [`protect-secrets.js`](protect-secrets.js) | Blocks any tool call (read/write/bash) touching `.env*`, `secrets/`, `credentials*`, SSH keys, `.npmrc`, `.pypirc`. |
|
||||
| [`audit-log.js`](audit-log.js) | Appends a one-line JSON record of every successful tool call to `.opencode/audit.jsonl`. |
|
||||
| [`audit-log.js`](audit-log.js) | Appends a one-line JSON record of every completed tool call to `.opencode/audit.jsonl`. |
|
||||
|
||||
## How they load
|
||||
|
||||
@@ -25,7 +25,7 @@ tail -f .opencode/audit.jsonl # watch tool calls live
|
||||
Sample line:
|
||||
|
||||
```json
|
||||
{"ts":"2026-05-18T19:30:12.451Z","tool":"edit","ok":true,"input_keys":["file_path","old_string","new_string"]}
|
||||
{"ts":"2026-06-08T19:30:12.451Z","tool":"edit","arg_keys":["filePath","oldString","newString"],"title":"src/api/auth.ts"}
|
||||
```
|
||||
|
||||
## Disabling temporarily
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// .opencode/plugins/audit-log.js
|
||||
//
|
||||
// Append a JSONL record of every successful tool call to .opencode/audit.jsonl.
|
||||
// Append a JSONL record of every completed tool call to .opencode/audit.jsonl.
|
||||
// Useful as an after-the-fact paper trail of what the agent did this session.
|
||||
//
|
||||
// Toggle off by deleting this file or by gating with an env var:
|
||||
@@ -15,19 +15,16 @@ export const AuditLog = async ({ directory }) => {
|
||||
await mkdir(dirname(logPath), { recursive: true });
|
||||
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
if (event?.type !== "tool.execute.after") return;
|
||||
|
||||
// `tool.execute.after` is a top-level hook with an (input, output) signature,
|
||||
// fired once a tool call completes. `input.tool`/`input.args` describe the
|
||||
// call; `output.title` is OpenCode's short summary of the result.
|
||||
"tool.execute.after": async (input, output) => {
|
||||
const record = {
|
||||
ts: new Date().toISOString(),
|
||||
tool: event.tool,
|
||||
ok: !event.error,
|
||||
// Capture small inputs only — full inputs can be huge (file content, diffs)
|
||||
input_keys: event.input ? Object.keys(event.input) : [],
|
||||
// Truncate long error messages
|
||||
error: event.error
|
||||
? String(event.error).slice(0, 240)
|
||||
: undefined,
|
||||
tool: input.tool,
|
||||
// Capture argument keys only — full args can be huge (file content, diffs)
|
||||
arg_keys: input.args ? Object.keys(input.args) : [],
|
||||
title: output?.title,
|
||||
};
|
||||
|
||||
await appendFile(logPath, JSON.stringify(record) + "\n");
|
||||
|
||||
@@ -7,27 +7,30 @@
|
||||
|
||||
const SENSITIVE = /(^|\/)(\.env(\..*)?|secrets|credentials|id_rsa|id_ed25519|\.npmrc|\.pypirc)(\b|\/)/i;
|
||||
|
||||
function pathFromInput(toolName, input) {
|
||||
if (!input || typeof input !== "object") return "";
|
||||
// Pull the most likely path/command field out of a tool's arguments.
|
||||
// `read`/`edit`/`write` use `filePath`; `bash` uses `command`; others vary.
|
||||
function targetFromArgs(args) {
|
||||
if (!args || typeof args !== "object") return "";
|
||||
return (
|
||||
input.path ??
|
||||
input.file_path ??
|
||||
input.filePath ??
|
||||
input.target ??
|
||||
input.command ?? // for bash tool, scan the command line itself
|
||||
args.filePath ??
|
||||
args.path ??
|
||||
args.file_path ??
|
||||
args.target ??
|
||||
args.command ?? // bash: scan the command line itself
|
||||
""
|
||||
);
|
||||
}
|
||||
|
||||
export const ProtectSecrets = async () => {
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
if (event?.type !== "tool.execute.before") return;
|
||||
|
||||
const candidate = pathFromInput(event.tool, event.input);
|
||||
// `tool.execute.before` is a top-level hook with an (input, output) signature.
|
||||
// `input.tool` is the tool name; `output.args` holds its (mutable) arguments.
|
||||
// Throwing here aborts the tool call before it runs.
|
||||
"tool.execute.before": async (input, output) => {
|
||||
const candidate = targetFromArgs(output?.args);
|
||||
if (candidate && SENSITIVE.test(String(candidate))) {
|
||||
throw new Error(
|
||||
`[protect-secrets] blocked ${event.tool} on sensitive path: ${candidate}`
|
||||
`[protect-secrets] blocked ${input.tool} on sensitive path: ${candidate}`
|
||||
);
|
||||
}
|
||||
},
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
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.
|
||||
|
||||
[](LICENSE)
|
||||
[](https://github.com/anomalyco/opencode/releases)
|
||||
[](#updates--deprecations)
|
||||
[](https://github.com/anomalyco/opencode/releases)
|
||||
[](#updates--deprecations)
|
||||
[](CONTRIBUTING.md)
|
||||
|
||||
```bash
|
||||
@@ -115,7 +115,7 @@ scoop install opencode # Windows
|
||||
choco install opencode # Windows
|
||||
sudo pacman -S opencode # Arch
|
||||
paru -S opencode-bin # Arch (AUR)
|
||||
mise use -g opencode # mise users
|
||||
mise use -g github:anomalyco/opencode # mise users
|
||||
nix run nixpkgs#opencode # Nix
|
||||
```
|
||||
|
||||
@@ -201,7 +201,7 @@ Per-agent model override:
|
||||
{
|
||||
"agent": {
|
||||
"plan": { "model": "anthropic/claude-haiku-4-5" },
|
||||
"deep-thinker": { "model": "openai/gpt-5", "reasoningEffort": "high" }
|
||||
"deep-thinker": { "model": "openai/gpt-5", "options": { "reasoningEffort": "high" } }
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -217,23 +217,23 @@ A curated, pay-as-you-go AI gateway. The OpenCode team tests and tunes models fo
|
||||
/models # browse the lineup
|
||||
```
|
||||
|
||||
**Pricing snapshot** *(verified 2026-05-18; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
|
||||
**Pricing snapshot** *(verified 2026-06-08; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
|
||||
|
||||
| Model ID | Input / Output (per MTok) | Reach for it when… |
|
||||
|---|---|---|
|
||||
| `opencode/claude-opus-4-7` | $5 / $25 | Complex reasoning, large refactors |
|
||||
| `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-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/qwen3.6-plus` | $0.50 / $3 | Budget-friendly heavy lifting |
|
||||
| `opencode/qwen3.7-plus` | $0.40 / $1.60 | Budget-friendly heavy lifting |
|
||||
|
||||
**Free tier** *(rotating, time-limited, for community feedback):* `deepseek-v4-flash-free`, `minimax-m2.5-free`, `nemotron-3-super-free`, `big-pickle` *(stealth)*.
|
||||
**Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `nemotron-3-ultra-free`.
|
||||
|
||||
> 40+ models total — full list, cached-read/write rates, GPT 5 Codex variants, GLM, Kimi, Claude Opus 4.5/4.6/4.1, etc.: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide: [`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.6-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-7`) 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -362,7 +362,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), `--share` (publish), `--format json` (machine-readable), `--file <path>` (attach), `--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+), `--dangerously-skip-permissions` (auto-approve everything not `deny` — **CI only**).
|
||||
|
||||
Sessions, stats, sharing:
|
||||
|
||||
@@ -529,7 +529,7 @@ Plus npm packages via the `plugin` array in `opencode.json`:
|
||||
|
||||
Auto-installed via Bun, cached under `~/.cache/opencode/node_modules/`.
|
||||
|
||||
Plugins receive `{ project, directory, worktree, client, $ }` and return event handlers. `$` is the Bun shell. Events span tools, files, sessions, messages, permissions, LSP, TUI — ~25 total.
|
||||
Plugins receive `{ project, directory, worktree, client, $ }` and return hooks. `$` is the Bun shell. Two shapes: typed hooks like `tool.execute.before`/`shell.env` that get `(input, output)`, and a generic `event` handler for the lifecycle stream (files, sessions, messages, permissions, LSP, TUI — ~26 events).
|
||||
|
||||
This repo ships two working examples in [`.opencode/plugins/`](.opencode/plugins/):
|
||||
|
||||
@@ -588,11 +588,11 @@ Filename → agent name. `frontend-engineer.md` → `@frontend-engineer` (subage
|
||||
| `subagent` | `@<name>` mentions only (runs in a child session) |
|
||||
| `all` | Both |
|
||||
|
||||
Bash permissions accept a **glob-pattern map** (`{"*": "ask", "git status*": "allow", "rm -rf*": "deny"}`) — most-specific match wins.
|
||||
Bash permissions accept a **glob-pattern map** (`{"*": "ask", "git status*": "allow", "rm -rf*": "deny"}`) — rules match in order and the **last matching rule wins**, so list the catch-all `*` first.
|
||||
|
||||
> 📐 This repo ships **drop-in specialist prompts** in [`specialized-agents/`](specialized-agents/) — backend, frontend, code reviewer, security reviewer, tech lead, database, UX. Copy any of them into `.opencode/agents/<name>.md` to use.
|
||||
|
||||
> 📚 Deep dive — full frontmatter key list, all 17 permission keys, JSON-form alternative: [`docs/agents.md`](docs/agents.md) · [`docs/reference/permissions.md`](docs/reference/permissions.md).
|
||||
> 📚 Deep dive — full frontmatter key list, all 15 permission keys, JSON-form alternative: [`docs/agents.md`](docs/agents.md) · [`docs/reference/permissions.md`](docs/reference/permissions.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -671,16 +671,22 @@ 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.15.4** *(2026-05-17)*. Run `opencode upgrade` to get it.
|
||||
**Current release:** **v1.16.2** *(2026-06-05)*. Run `opencode upgrade` to get it.
|
||||
|
||||
**Recent highlights:**
|
||||
**New in v1.16:**
|
||||
|
||||
- 🆕 **Agent Skills compatibility** — auto-discoverable workflows via `SKILL.md` (Claude Code-compatible).
|
||||
- 🆕 **Glob-pattern bash permissions** — fine-grained allow/ask/deny per command pattern.
|
||||
- 🆕 **Remote MCP with auto-OAuth** — Dynamic Client Registration handled out of the box.
|
||||
- 🆕 **Desktop app (beta)** — macOS, Windows, Linux at [opencode.ai/download](https://opencode.ai/download).
|
||||
- 🆕 **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.
|
||||
- 🆕 **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).
|
||||
|
||||
**Still recent (v1.15):**
|
||||
|
||||
- **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.
|
||||
|
||||
> 💡 Source of truth: [GitHub releases](https://github.com/anomalyco/opencode/releases).
|
||||
@@ -705,4 +711,4 @@ 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-05-18 · OpenCode v1.15.4 · Spotted something stale? [Open an issue](../../issues) or send a PR — see [`CONTRIBUTING.md`](CONTRIBUTING.md).*
|
||||
*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).*
|
||||
|
||||
+14
-11
@@ -25,6 +25,8 @@ 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.
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Senior frontend engineer — Tailwind + React + TypeScript expert
|
||||
@@ -61,10 +63,10 @@ Verified against the [config JSON schema's `AgentConfig`](https://opencode.ai/co
|
||||
| `model` | `provider/model-id` | Per-agent model override |
|
||||
| `temperature` · `top_p` | number | Sampling controls |
|
||||
| `permission` | object | Per-tool `allow`/`ask`/`deny` (see below) |
|
||||
| `tools` | object | Boolean per tool — `{"websearch": false}` |
|
||||
| `tools` | object | *Deprecated — prefer `permission`.* Boolean per tool — `{"websearch": false}` |
|
||||
| `prompt` *(JSON form only)* | string | System prompt; alternative to markdown body |
|
||||
| `maxSteps` | number | Hard cap on agent steps in one invocation |
|
||||
| `steps` | array | Scripted step sequence (advanced) |
|
||||
| `steps` | number | Max agentic iterations before a forced text-only response |
|
||||
| `maxSteps` | number | *Deprecated — use `steps`.* |
|
||||
| `disable` | boolean | Disable an agent entirely |
|
||||
| `hidden` | boolean | Hide from the UI but keep available |
|
||||
| `color` | string | UI accent color |
|
||||
@@ -100,7 +102,6 @@ Permission keys (verified against `PermissionConfig` in the [config JSON schema]
|
||||
| `todowrite` | the in-session todo list |
|
||||
| `question` | the `question` tool |
|
||||
| `external_directory` | files outside the project root |
|
||||
| `repo_clone` · `repo_overview` | repo-level operations |
|
||||
| `webfetch` · `websearch` | network access |
|
||||
| `lsp` | language server tools |
|
||||
| `skill` | agent skill loading |
|
||||
@@ -110,18 +111,18 @@ Three values everywhere: `"allow"` (no prompt) · `"ask"` (prompt user) · `"den
|
||||
|
||||
### Glob-pattern bash
|
||||
|
||||
The `bash` key can be a single value or a glob-map. **Order matters**: most specific patterns first.
|
||||
The `bash` key can be a single value or a glob-map. **Order matters**: rules are matched in order and the **last matching rule wins**, so put the catch-all `*` first and the more specific overrides after it.
|
||||
|
||||
```json
|
||||
{
|
||||
"permission": {
|
||||
"bash": {
|
||||
"rm -rf*": "deny",
|
||||
"git push --force*": "deny",
|
||||
"*": "ask",
|
||||
"git status*": "allow",
|
||||
"git diff*": "allow",
|
||||
"pnpm test*": "allow",
|
||||
"*": "ask"
|
||||
"git push --force*": "deny",
|
||||
"rm -rf*": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -136,9 +137,9 @@ Use this to keep an agent productive (no constant prompting for safe reads) whil
|
||||
"agent": {
|
||||
"explore": { "model": "opencode/qwen3.6-plus" },
|
||||
"scout": { "model": "opencode/qwen3.6-plus" },
|
||||
"plan": { "model": "opencode/claude-opus-4-7" },
|
||||
"plan": { "model": "opencode/claude-opus-4-8" },
|
||||
"build": { "model": "opencode/claude-sonnet-4-6" },
|
||||
"deep-thinker": { "model": "openai/gpt-5", "reasoningEffort": "high" }
|
||||
"deep-thinker": { "model": "openai/gpt-5", "options": { "reasoningEffort": "high" } }
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -150,6 +151,8 @@ If unspecified:
|
||||
|
||||
## Tools per agent
|
||||
|
||||
> ⚠️ The `tools` map is **deprecated** in favor of the `permission` field (set a tool to `"deny"` to disable it). It still works and remains the simplest way to gate MCP tools by glob, but prefer `permission` for new configs.
|
||||
|
||||
The `tools` map enables/disables individual tools by name, including MCP tools (use glob patterns):
|
||||
|
||||
```json
|
||||
@@ -224,6 +227,6 @@ permission:
|
||||
|
||||
## Drop-in specialists
|
||||
|
||||
This repo ships 10 production-ready prompts in [`specialized-agents/`](../specialized-agents/). Copy any of them to `.opencode/agents/<name>.md` to use as a starting point.
|
||||
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).
|
||||
|
||||
+2
-2
@@ -114,7 +114,7 @@ Invoke with: `/scaffold-component UserAvatar`
|
||||
description: Deep architectural review (isolated context)
|
||||
agent: build
|
||||
subtask: true
|
||||
model: opencode/claude-opus-4-7
|
||||
model: opencode/claude-opus-4-8
|
||||
---
|
||||
|
||||
You are reviewing the architectural integrity of $ARGUMENTS.
|
||||
@@ -157,7 +157,7 @@ If a command always runs with a particular model or agent, put it in the frontma
|
||||
---
|
||||
description: Long, deep refactor planning (Opus only)
|
||||
agent: plan
|
||||
model: opencode/claude-opus-4-7
|
||||
model: opencode/claude-opus-4-8
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
+5
-2
@@ -123,15 +123,18 @@ For servers that require pre-registered credentials:
|
||||
}
|
||||
```
|
||||
|
||||
### Managing OAuth from the CLI
|
||||
### Managing servers from the CLI
|
||||
|
||||
```bash
|
||||
opencode mcp add # interactively register a local or remote server
|
||||
opencode mcp list # show servers and auth status
|
||||
opencode mcp auth sentry # complete or refresh OAuth flow
|
||||
opencode mcp logout sentry # forget stored credentials
|
||||
opencode mcp debug sentry # diagnose connection issues
|
||||
opencode mcp list # show servers and auth status
|
||||
```
|
||||
|
||||
`opencode mcp add` walks you through type, command/URL, and headers, then writes the entry to your config — the no-hand-editing alternative to the JSON blocks above.
|
||||
|
||||
## Token budget warning
|
||||
|
||||
MCP tools land in the model's tool surface every turn. Heavy servers (e.g., a full GitHub MCP with dozens of tools) can easily eat 10K+ tokens of context — purely for tool *descriptions* the model may never actually call.
|
||||
|
||||
+6
-4
@@ -114,9 +114,11 @@ OpenCode equivalent (`.opencode/plugins/protect-env.js`):
|
||||
```javascript
|
||||
export const ProtectEnv = async () => {
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
if (event.type === "tool.execute.before" && event.tool === "edit") {
|
||||
if ((event.input?.path ?? "").includes(".env")) {
|
||||
// `tool.execute.before` is a top-level hook: (input, output). `input.tool`
|
||||
// names the tool; `output.args` holds its arguments. Throw to block.
|
||||
"tool.execute.before": async (input, output) => {
|
||||
if (input.tool === "edit" || input.tool === "write") {
|
||||
if ((output?.args?.filePath ?? "").includes(".env")) {
|
||||
throw new Error("Plugin blocked: cannot write .env");
|
||||
}
|
||||
}
|
||||
@@ -226,4 +228,4 @@ Migration is mostly muscle-memory adjustment, not config porting.
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
+31
-23
@@ -57,7 +57,7 @@ opencode plugin --global opencode-wakatime
|
||||
|
||||
## Plugin API
|
||||
|
||||
A plugin is a default-export async function returning an object of event handlers:
|
||||
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:
|
||||
|
||||
```javascript
|
||||
// .opencode/plugins/notify-on-idle.js
|
||||
@@ -82,13 +82,24 @@ export const NotifyOnIdle = async ({ project, client, $, directory, worktree })
|
||||
| `client` | OpenCode SDK client — call back into OpenCode from inside the plugin |
|
||||
| `$` | Bun shell — run commands; supports tagged-template syntax |
|
||||
|
||||
### Available events
|
||||
### Hooks and events
|
||||
|
||||
Two distinct shapes — don't confuse them. **Typed hooks** are top-level keys called with `(input, output)`; use them to inspect or mutate one operation (and `throw` to block it). The generic **`event`** handler receives a read-only lifecycle stream you match on `event.type`.
|
||||
|
||||
Verified against the [Plugins doc](https://opencode.ai/docs/plugins):
|
||||
|
||||
| Category | Events |
|
||||
**Typed hooks** — `"hook.name": async (input, output) => { … }`:
|
||||
|
||||
| Hook | Fires | Key fields |
|
||||
|---|---|---|
|
||||
| `tool.execute.before` | Before a tool runs | `input.tool`; `output.args` (mutable) — `throw` to block |
|
||||
| `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) |
|
||||
|
||||
**Event stream** — `event: async ({ event }) => { if (event.type === …) }`:
|
||||
|
||||
| Category | `event.type` values |
|
||||
|---|---|
|
||||
| **Tools** | `tool.execute.before`, `tool.execute.after` |
|
||||
| **Files** | `file.edited`, `file.watcher.updated` |
|
||||
| **Sessions** | `session.created`, `session.updated`, `session.compacted`, `session.idle`, `session.status`, `session.error`, `session.diff`, `session.deleted` |
|
||||
| **Messages** | `message.updated`, `message.removed`, `message.part.updated`, `message.part.removed` |
|
||||
@@ -96,11 +107,11 @@ Verified against the [Plugins doc](https://opencode.ai/docs/plugins):
|
||||
| **Permissions** | `permission.asked`, `permission.replied` |
|
||||
| **LSP** | `lsp.client.diagnostics`, `lsp.updated` |
|
||||
| **Server / installation** | `server.connected`, `installation.updated` |
|
||||
| **Shell** | `shell.env` |
|
||||
| **Todo** | `todo.updated` |
|
||||
| **TUI** | `tui.prompt.append`, `tui.command.execute`, `tui.toast.show` |
|
||||
| **Experimental** | `experimental.session.compacting` |
|
||||
|
||||
> 📚 Each event carries event-specific payload. Full reference: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
|
||||
> 📚 Each hook/event carries its own payload. Full reference: [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
|
||||
|
||||
## Common patterns
|
||||
|
||||
@@ -140,18 +151,15 @@ export const AuditLog = async ({ directory }) => {
|
||||
const logPath = `${directory}/.opencode/audit.jsonl`;
|
||||
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
if (event.type === "tool.execute.after") {
|
||||
await appendFile(
|
||||
logPath,
|
||||
JSON.stringify({
|
||||
ts: new Date().toISOString(),
|
||||
tool: event.tool,
|
||||
input: event.input,
|
||||
success: !event.error,
|
||||
}) + "\n"
|
||||
);
|
||||
}
|
||||
"tool.execute.after": async (input, output) => {
|
||||
await appendFile(
|
||||
logPath,
|
||||
JSON.stringify({
|
||||
ts: new Date().toISOString(),
|
||||
tool: input.tool,
|
||||
title: output?.title,
|
||||
}) + "\n"
|
||||
);
|
||||
},
|
||||
};
|
||||
};
|
||||
@@ -175,14 +183,14 @@ export const NotifyOnIdle = async ({ $ }) => {
|
||||
|
||||
### 4. Block sensitive paths
|
||||
|
||||
Prevent any edits to `.env` files or `secrets/` directories:
|
||||
Prevent any edit to `.env` files or `secrets/` directories. `tool.execute.before` is a top-level hook — throwing aborts the call before it runs:
|
||||
|
||||
```javascript
|
||||
export const ProtectSecrets = async ({ client }) => {
|
||||
export const ProtectSecrets = async () => {
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
if (event.type === "tool.execute.before" && event.tool === "edit") {
|
||||
const path = event.input?.path ?? "";
|
||||
"tool.execute.before": async (input, output) => {
|
||||
if (input.tool === "edit" || input.tool === "write") {
|
||||
const path = output?.args?.filePath ?? "";
|
||||
if (/\.env|secrets\//i.test(path)) {
|
||||
throw new Error(`Plugin blocked: ${path} is a protected path`);
|
||||
}
|
||||
|
||||
+4
-3
@@ -14,9 +14,10 @@ curl -fsSL https://opencode.ai/install | bash
|
||||
npm i -g opencode-ai@latest
|
||||
brew install anomalyco/tap/opencode
|
||||
scoop install opencode
|
||||
choco install opencode
|
||||
sudo pacman -S opencode
|
||||
paru -S opencode-bin
|
||||
mise use -g opencode
|
||||
mise use -g github:anomalyco/opencode
|
||||
nix run nixpkgs#opencode
|
||||
```
|
||||
|
||||
@@ -104,9 +105,9 @@ Run `opencode auth login` and pick a provider. Re-run `/connect` from inside the
|
||||
|
||||
```bash
|
||||
opencode upgrade # latest
|
||||
opencode upgrade v1.15.0 # specific version
|
||||
opencode upgrade v1.16.0 # specific version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
@@ -4,16 +4,30 @@
|
||||
|
||||
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.15.x — May 2026
|
||||
## v1.16.x — June 2026
|
||||
|
||||
Current stable line. Run `opencode upgrade` to get the latest.
|
||||
|
||||
**Verified latest release:** `v1.15.4`, published 2026-05-17 17:44 UTC ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.15.4)).
|
||||
**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.
|
||||
|
||||
**Highlights:**
|
||||
|
||||
- **File-based agent loading & skill discovery** — drop-in agent markdown files and `SKILL.md` discovery are GA; scaffold an agent with `opencode agent create`.
|
||||
- **Managed workspace cloning** — clones keep dirty and untracked files intact.
|
||||
- **Session mobility** — move sessions between workspaces and directories.
|
||||
- **`opencode run --replay`** — interactive replay of 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, in-app updates).
|
||||
- **GitHub extension** now requires an existing git author identity before committing.
|
||||
|
||||
## v1.15.x — May 2026
|
||||
|
||||
**Latest:** `v1.15.4`, published 2026-05-17 17:44 UTC ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.15.4)).
|
||||
|
||||
**Highlights:**
|
||||
|
||||
- **Agent Skills compatibility** — discoverable workflows via `SKILL.md` folders; compatible with Claude Code skill format.
|
||||
- **Glob-pattern bash permissions** — fine-grained `allow`/`ask`/`deny` per command pattern, with most-specific wins.
|
||||
- **Glob-pattern bash permissions** — fine-grained `allow`/`ask`/`deny` per command pattern; rules match in order with the last match winning (list `*` first).
|
||||
- **Managed configs** — `/Library/Application Support/opencode/` (macOS), `/etc/opencode/` (Linux), `%ProgramData%\opencode` (Windows), plus macOS MDM preferences for enterprise rollouts.
|
||||
- **ACP server** (`opencode acp`) — Agent Client Protocol server for editor integrations.
|
||||
- **Remote MCP with auto-OAuth** — Dynamic Client Registration (RFC 7591) handled automatically.
|
||||
@@ -61,4 +75,4 @@ For the current state, check the [GitHub repo](https://github.com/anomalyco/open
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · 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-06-08 · For the authoritative list, see [GitHub releases](https://github.com/anomalyco/opencode/releases) · Canonical docs: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
@@ -71,6 +71,8 @@ opencode run --agent plan --model anthropic/claude-haiku-4-5 "audit src/ for mis
|
||||
| `--port` | Port for the local server backing this run |
|
||||
| `--variant <name>` | Model variant |
|
||||
| `--thinking` | Show thinking blocks |
|
||||
| `--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.** |
|
||||
|
||||
@@ -283,7 +285,7 @@ Update OpenCode to the latest or a specific version.
|
||||
|
||||
```bash
|
||||
opencode upgrade
|
||||
opencode upgrade v1.15.0
|
||||
opencode upgrade v1.16.0
|
||||
opencode upgrade --method brew # force the install method
|
||||
```
|
||||
|
||||
|
||||
@@ -249,4 +249,4 @@ export EDITOR='nvim' # Neovim
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
@@ -66,4 +66,4 @@ These aren't OpenCode-specific, but the patterns transfer.
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
@@ -12,7 +12,7 @@ Every permission accepts one of:
|
||||
| `"ask"` | User is prompted to approve each use |
|
||||
| `"deny"` | Tool is blocked outright |
|
||||
|
||||
For `bash` (and any rule-style permission), you can also pass a **glob-pattern map** keyed by command pattern — most-specific wins, `*` is the catch-all.
|
||||
For `bash` (and any rule-style permission), you can also pass a **glob-pattern map** keyed by command pattern. Rules are matched in order and the **last matching rule wins**, so list the catch-all `*` first and put more specific overrides after it.
|
||||
|
||||
## Permission keys → what they gate
|
||||
|
||||
@@ -26,13 +26,13 @@ For `bash` (and any rule-style permission), you can also pass a **glob-pattern m
|
||||
| `todowrite` | in-session todo list |
|
||||
| `question` | the `question` tool |
|
||||
| `external_directory` | files outside the project root |
|
||||
| `repo_clone` | cloning dependency repos into OpenCode's cache (used by `scout`) |
|
||||
| `repo_overview` | repo-summary operations |
|
||||
| `webfetch` · `websearch` | network access |
|
||||
| `lsp` | language-server tools |
|
||||
| `skill` | loading agent skills |
|
||||
| `doom_loop` | runaway-loop safeguards |
|
||||
|
||||
That's the full set — **15 keys** (`read`, `edit`, `glob`, `grep`, `list`, `bash`, `task`, `external_directory`, `todowrite`, `question`, `webfetch`, `websearch`, `lsp`, `doom_loop`, `skill`), per the config schema.
|
||||
|
||||
> Note: `write` and `apply_patch` are both gated under the `edit` key, not separately.
|
||||
|
||||
## Built-in tool list
|
||||
@@ -116,12 +116,12 @@ The `bash` key accepts a glob-pattern map. Patterns are matched against the full
|
||||
{
|
||||
"permission": {
|
||||
"bash": {
|
||||
"rm -rf*": "deny",
|
||||
"git push --force*": "deny",
|
||||
"*": "ask",
|
||||
"git status*": "allow",
|
||||
"git diff*": "allow",
|
||||
"pnpm test*": "allow",
|
||||
"*": "ask"
|
||||
"git push --force*": "deny",
|
||||
"rm -rf*": "deny"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -129,7 +129,7 @@ The `bash` key accepts a glob-pattern map. Patterns are matched against the full
|
||||
|
||||
**Matching rules:**
|
||||
|
||||
- Patterns are evaluated by specificity — most specific match wins; `*` is the catch-all.
|
||||
- Rules are matched in order and the **last matching rule wins**. Put the catch-all `*` **first**, then list more specific overrides after it — a trailing `*` would override everything above it.
|
||||
- `*` matches zero or more characters (including spaces).
|
||||
- `?` matches exactly one character.
|
||||
- Literal text matches exactly.
|
||||
|
||||
+8
-6
@@ -58,11 +58,11 @@ version bump before doing anything destructive.
|
||||
|
||||
| Key | Required | Constraints |
|
||||
|---|---|---|
|
||||
| `name` | yes | `^[a-z0-9]+(-[a-z0-9]+)*$`, 1–64 chars — lowercase alphanumeric with single hyphens |
|
||||
| `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 |
|
||||
| `metadata` | no | Arbitrary structured metadata |
|
||||
| `metadata` | no | String-to-string map (keys and values are both strings) |
|
||||
|
||||
### Why the `description` matters
|
||||
|
||||
@@ -84,16 +84,18 @@ Anatomy of a good description:
|
||||
|
||||
## Where skills live
|
||||
|
||||
OpenCode searches multiple locations:
|
||||
OpenCode searches six locations — three project-local, three global:
|
||||
|
||||
| Location | Scope |
|
||||
|---|---|
|
||||
| `.opencode/skills/<name>/SKILL.md` | Project |
|
||||
| `.claude/skills/<name>/SKILL.md` | Project — Claude Code compatibility |
|
||||
| `.agents/skills/<name>/SKILL.md` | Project — Agent-format compatibility |
|
||||
| `~/.config/opencode/skills/<name>/SKILL.md` | Global |
|
||||
| `.claude/skills/<name>/SKILL.md` | Claude Code compatibility |
|
||||
| `.agents/skills/<name>/SKILL.md` | Agent-format compatibility |
|
||||
| `~/.claude/skills/<name>/SKILL.md` | Global — Claude Code compatibility |
|
||||
| `~/.agents/skills/<name>/SKILL.md` | Global — Agent-format compatibility |
|
||||
|
||||
Project skills take precedence over global. Same-named skills in different locations: project wins.
|
||||
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.
|
||||
|
||||
## Permissions
|
||||
|
||||
|
||||
@@ -43,6 +43,7 @@ Use the **leader key** (default `ctrl+x`) for session-level actions, and readlin
|
||||
| Key | Action |
|
||||
|---|---|
|
||||
| `Tab` | Cycle primary agents (`build` ↔ `plan` ↔ custom primaries) |
|
||||
| `shift+tab` | Cycle primary agents in reverse |
|
||||
| `Esc` | Cancel / dismiss |
|
||||
| `ctrl+c` / `ctrl+d` | Exit |
|
||||
|
||||
@@ -113,6 +114,8 @@ Drop a `tui.json` next to your `opencode.json`:
|
||||
"theme": "tokyonight",
|
||||
"leader_timeout": 2000,
|
||||
"scroll_speed": 3,
|
||||
"diff_style": "auto",
|
||||
"mouse": true,
|
||||
"keybinds": {
|
||||
"command_list": "ctrl+p",
|
||||
"messages_copy": ["<leader>y", "ctrl+shift+c"],
|
||||
@@ -129,6 +132,8 @@ Drop a `tui.json` next to your `opencode.json`:
|
||||
|
||||
Set a binding to `"none"` or `false` to disable. Arrays bind multiple shortcuts to the same action.
|
||||
|
||||
Other top-level keys worth knowing: `diff_style` (`"auto"` adapts to terminal width, `"stacked"` forces single-column diffs), `mouse` (capture toggle, default `true`), and `scroll_acceleration` (macOS-style smooth scroll that overrides `scroll_speed`). The `attention` block also takes `sound_pack` (default `"opencode.default"`) and a `sounds` map for per-event overrides (`default`, `question`, `permission`, `error`, `done`, `subagent_done`).
|
||||
|
||||
## Themes
|
||||
|
||||
Set the theme in `tui.json` or with `/themes` interactively.
|
||||
|
||||
+3
-1
@@ -159,6 +159,8 @@ Same idea on Buildkite, CircleCI, Jenkins — install the CLI, set the env var,
|
||||
|
||||
`--dangerously-skip-permissions` is available for fully unattended runs — 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.
|
||||
|
||||
## 7. Visual iteration
|
||||
|
||||
Goal: implement UI to match a mock.
|
||||
@@ -184,4 +186,4 @@ Two-three iteration rounds usually produces a close visual match. Multimodal mod
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
+16
-13
@@ -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-05-18. 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-06-08. Pricing and model availability change frequently; check the docs before quoting numbers.)*
|
||||
|
||||
## When to reach for Zen vs. direct providers
|
||||
|
||||
@@ -43,21 +43,21 @@ In `opencode.json`, reference a Zen model with the `opencode/` prefix:
|
||||
}
|
||||
```
|
||||
|
||||
> Slug format: keep the dots in the upstream model name where they exist (`gpt-5.5`, `gemini-3.1-pro`, `qwen3.6-plus`, `minimax-m2.5`); Anthropic IDs use hyphens (`claude-opus-4-7`, `claude-sonnet-4-6`).
|
||||
> Slug format: keep the dots in the upstream model name where they exist (`gpt-5.5`, `gemini-3.1-pro`, `qwen3.7-plus`, `minimax-m2.7`); Anthropic IDs use hyphens (`claude-opus-4-8`, `claude-sonnet-4-6`).
|
||||
|
||||
## Available models
|
||||
|
||||
Selected lineup below. **For the full list (40+ 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 list (50+ entries, 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-7` | $5 / $25 | Flagship reasoning — complex refactors, multi-file work |
|
||||
| `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-haiku-4-5` | $1 / $5 | Cheap, fast — title generation, simple Q&A |
|
||||
|
||||
Older versions (`claude-opus-4-6`, `claude-opus-4-5`, `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-opus-4-1`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-3-5-haiku`) are also available — see the full list.
|
||||
|
||||
### OpenAI family
|
||||
|
||||
@@ -66,6 +66,7 @@ Older versions (`claude-opus-4-6`, `claude-opus-4-5`, `claude-sonnet-4-5`, `clau
|
||||
| `opencode/gpt-5.5` *(≤272K)* | $5 / $30 | Long-context flagship |
|
||||
| `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-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 |
|
||||
@@ -76,22 +77,24 @@ GPT 5.1 / 5 / 5-codex / 5-nano are also available with their own pricing.
|
||||
|
||||
| Model ID | Input / Output (per MTok) | Notes |
|
||||
|---|---|---|
|
||||
| `opencode/gemini-3.5-flash` | $1.50 / $9 | Newest fast Gemini |
|
||||
| `opencode/gemini-3.1-pro` *(≤200K)* | $2 / $12 | Multimodal flagship |
|
||||
| `opencode/gemini-3-flash` | $0.50 / $3 | Fast Gemini variant |
|
||||
| `opencode/qwen3.6-plus` | $0.50 / $3 | Budget-friendly heavy lifting |
|
||||
| `opencode/qwen3.5-plus` | $0.20 / $1.20 | Even cheaper |
|
||||
| `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/kimi-k2.6` | $0.95 / $4 | Moonshot lineup |
|
||||
| `opencode/glm-5.1` | $1.40 / $4.40 | Zhipu lineup |
|
||||
| `opencode/minimax-m2.7` | $0.30 / $1.20 | MiniMax current |
|
||||
| `opencode/grok-build-0.1` | $1 / $2 | xAI coding model |
|
||||
|
||||
### Free tier (rotating, time-limited)
|
||||
|
||||
For community feedback during model rollout:
|
||||
|
||||
- `opencode/deepseek-v4-flash-free`
|
||||
- `opencode/minimax-m2.5-free`
|
||||
- `opencode/nemotron-3-super-free`
|
||||
- `opencode/big-pickle` *(stealth model)*
|
||||
- `opencode/deepseek-v4-flash-free`
|
||||
- `opencode/mimo-v2.5-free`
|
||||
- `opencode/nemotron-3-ultra-free`
|
||||
|
||||
Great for learning OpenCode without burning a budget.
|
||||
|
||||
@@ -128,7 +131,7 @@ For complex tasks, plan with the smartest model, then hand the atomic plan to a
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"plan": { "model": "opencode/claude-opus-4-7" },
|
||||
"plan": { "model": "opencode/claude-opus-4-8" },
|
||||
"build": { "model": "opencode/claude-sonnet-4-6" }
|
||||
}
|
||||
}
|
||||
@@ -180,4 +183,4 @@ Both are gateways. Zen is **curated** — the OpenCode team picks and tunes mode
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
*Last reviewed: 2026-06-08 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
|
||||
@@ -19,6 +19,8 @@
|
||||
|
||||
If everything you need is already in local files, you probably don't need MCP yet.
|
||||
|
||||
> 💡 Each walkthrough below shows the `opencode.json` entry to hand-edit. To register a server interactively instead, run `opencode mcp add` and answer the prompts.
|
||||
|
||||
## 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:
|
||||
|
||||
+2
-2
@@ -21,11 +21,11 @@
|
||||
"wc *": "allow",
|
||||
"head *": "allow",
|
||||
"tail *": "allow",
|
||||
"rm -rf*": "deny",
|
||||
"curl *": "ask",
|
||||
"rm *": "ask",
|
||||
"rm -rf*": "deny",
|
||||
"git push --force*": "deny",
|
||||
"git reset --hard*": "deny",
|
||||
"curl *": "ask",
|
||||
"npm publish*": "deny"
|
||||
},
|
||||
"webfetch": "ask",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
description: Tech lead — makes architectural decisions, sequences work, surfaces trade-offs across teams. Plans more than it implements.
|
||||
mode: all
|
||||
model: anthropic/claude-opus-4-7
|
||||
model: anthropic/claude-opus-4-8
|
||||
temperature: 0.3
|
||||
permission:
|
||||
edit: ask
|
||||
|
||||
Reference in New Issue
Block a user