diff --git a/README.md b/README.md
index 3f5d131..51c8507 100644
--- a/README.md
+++ b/README.md
@@ -13,23 +13,389 @@ curl -fsSL https://opencode.ai/install | bash
**Who this is for:** Developers using (or about to use) [OpenCode](https://opencode.ai). Beginners get a guided path; power users get depth on Custom Commands, Skills, Plugins, MCP, and Agents.
-> βοΈ **Not affiliated with the OpenCode team.** This is a community-maintained guide. For the canonical, authoritative source, always check [opencode.ai/docs](https://opencode.ai/docs/) and [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode).
+> βοΈ **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).
---
## π§ Choose your path
-| You are⦠| Start here | Time |
+| You are⦠| Start with | Time |
|---|---|---|
-| π **New to OpenCode** | [Setup](#opencode-setup) β [Modes & Prompting](#prompt-engineering-deep-dive) β [Your First Command](#custom-commands) | ~15 min |
-| β‘ **Already using it, want depth** | [Custom Commands](#custom-commands) Β· [Skills](#agent-skills) Β· [Plugins](#plugins) Β· [MCP](#model-context-protocol-mcp) | ~20 min each |
-| π§ **Configuring teams or running headless** | [Custom Agents](#custom-agents) Β· [Headless & CI](#headless--ci-usage) Β· [OpenCode Zen](#opencode-zen) | varies |
+| π **New to OpenCode** | [What is it](#what-is-opencode) β [Setup](#setup) β [Prompt Engineering](#prompt-engineering) | ~15 min |
+| β‘ **Already using it** | [Custom Commands](#custom-commands) Β· [Skills](#agent-skills) Β· [Plugins](#plugins) Β· [MCP](#mcp-servers) | ~20 min each |
+| π§ **Configuring or headless** | [Agents](#agents) Β· [Headless & CI](#headless--ci) Β· [Models & Providers](#models--providers) | varies |
+
+
+
+
+
+
+
+
+
+
+
---
-## π§ When to use what
+## Getting started
-OpenCode has five extension points. Pick by trigger and surface:
+### 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.
+
+**Three things it does that a chat UI can't:**
+
+- **Reads your actual repo** β not pasted snippets. Greps your files, follows imports, grounds answers in real context using built-in `read`/`grep`/`glob` tools.
+- **Edits in place and runs your stack** β diff-aware `edit`/`write`/`apply_patch`, then `bash` to run your tests, linter, or build on the spot.
+- **Composes with the rest of your toolchain** β multi-provider models, custom slash commands, agent skills, JS/TS plugins, MCP servers, LSP, formatters, and an HTTP server for CI use.
+
+**Three interfaces:**
+
+| Surface | Command | When |
+|---|---|---|
+| **TUI** (default) | `opencode` | Interactive day-to-day work in your terminal |
+| **CLI / headless** | `opencode run ""` | Scripts, CI jobs, one-shot prompts |
+| **Server** | `opencode serve` or `opencode web` | Headless API, web UI, or remote attach |
+
+```bash
+opencode # start TUI in the current repo
+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.
+
+> β οΈ **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.
+
+---
+
+### When OpenCode isn't the right tool
+
+| 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. |
+| **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. |
+| **Plugins run arbitrary code** | Any plugin β local or npm β has full user permissions. Audit before installing. |
+| **Free Zen models are time-limited** | The [Zen docs](https://opencode.ai/docs/zen) call them "available for a limited time." Don't build production on them. |
+| **Docs lag shipping** | OpenCode moves fast. This guide and even the official docs occasionally trail the actual binary. |
+| **Not a substitute for code review** | Diff-aware edits + passing tests don't guarantee correct, secure, or maintainable code. Treat AI output as a junior teammate's PR. |
+
+**When something else fits better:**
+
+- Want a polished single-vendor product β **Claude Code** or **Cursor**.
+- 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.
+
+> OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.
+
+---
+
+### Setup
+
+> β±οΈ **5 minutes** from zero to first AI-assisted commit.
+
+#### 1. Install
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+Other supported installers (pick whichever you already use):
+
+```bash
+npm i -g opencode-ai@latest # npm / pnpm / yarn / bun all work
+brew install anomalyco/tap/opencode # macOS / Linux
+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
+nix run nixpkgs#opencode # Nix
+```
+
+A desktop app for macOS / Windows / Linux is in beta at [opencode.ai/download](https://opencode.ai/download).
+
+#### 2. Authenticate
+
+```bash
+opencode auth login # interactive provider picker
+opencode auth list # see who you're signed in to
+```
+
+Or from inside the TUI: `/connect`. Provider options covered in the next section.
+
+#### 3. First prompt
+
+```bash
+cd ~/your-project
+opencode
+```
+
+Try one of these:
+
+- `explain what this codebase does`
+- `add a README section about installation`
+- `find and fix the failing test in src/api.test.ts`
+
+#### 4. Generate an `AGENTS.md`
+
+```
+/init
+```
+
+`/init` generates an `AGENTS.md` β your project's "house rules" that OpenCode reads every session. Commit it. More in [Prompt Engineering](#prompt-engineering).
+
+> π **Coming from Claude Code?** OpenCode reads `CLAUDE.md` as a fallback if no `AGENTS.md` exists. Disable with `OPENCODE_DISABLE_CLAUDE_CODE=1` once migrated.
+
+#### 5. (Bonus) See a real configured project
+
+This repo's own [`.opencode/`](.opencode/) directory is a working example:
+
+| Path | What it does |
+|---|---|
+| [`.opencode/agents/`](.opencode/agents) | Custom agent definitions (markdown + YAML) |
+| [`.opencode/commands/`](.opencode/commands) | Custom slash commands |
+| [`.opencode/plugins/`](.opencode/plugins) | Working JS plugins (audit log, secret blocker) |
+| [`.opencode/skills/`](.opencode/skills) | Agent skills with `SKILL.md` files |
+| [`AGENTS.md`](AGENTS.md) | Project instructions OpenCode reads every session |
+| [`opencode.json`](opencode.json) | Project config with safe defaults |
+
+---
+
+### Models & Providers
+
+OpenCode is **provider-agnostic**. Three 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 |
+| **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.
+
+#### Direct provider config
+
+```json
+{
+ "$schema": "https://opencode.ai/config.json",
+ "model": "anthropic/claude-sonnet-4-5",
+ "provider": {
+ "anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } },
+ "openai": { "options": { "apiKey": "{file:~/.secrets/openai-key}" } }
+ }
+}
+```
+
+Variable substitution: `{env:NAME}` (environment) or `{file:./path}` (file content, absolute or relative).
+
+Per-agent model override:
+
+```json
+{
+ "agent": {
+ "plan": { "model": "anthropic/claude-haiku-4-5" },
+ "deep-thinker": { "model": "openai/gpt-5", "reasoningEffort": "high" }
+ }
+}
+```
+
+#### OpenCode Zen
+
+A curated, pay-as-you-go AI gateway. The OpenCode team tests and tunes models for coding-agent workloads; you get one key and a benchmarked lineup. Reference Zen models with the `opencode/` namespace.
+
+```bash
+# 1. Sign up at https://opencode.ai/auth, add billing, copy API key
+# 2. In OpenCode:
+/connect # pick "OpenCode Zen", paste key
+/models # browse the lineup
+```
+
+**Pricing snapshot** *(verified 2026-05-18; 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-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 |
+
+**Free tier** *(rotating, time-limited, for community feedback):* `deepseek-v4-flash-free`, `minimax-m2.5-free`, `nemotron-3-super-free`, `big-pickle` *(stealth)*.
+
+> 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).
+
+> π‘ **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.
+
+---
+
+## Using OpenCode
+
+### Prompt Engineering
+
+> **π Project Initialization.** Run `/init` to auto-generate an `AGENTS.md`. Treat it like any frequently-used prompt β iterate on it. Don't just dump 500 lines and forget.
+
+#### Plan β Build cycle
+
+Two primary agents you toggle with **Tab**:
+
+| Agent | What changes | Use it for |
+|---|---|---|
+| **`plan`** | `edit` and `bash` default to `ask` β analysis without surprise writes | Reading code, designing approaches, reviewing diffs |
+| **`build`** | Full tool access (default) | Implementation, refactors, running tests |
+
+Natural workflow:
+
+```text
+[plan] > how would you implement OAuth for this app?
+ (reads, plans, proposes β no writes)
+[plan] >
+[build] > do it
+ (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).
+
+#### File references and shell
+
+| Syntax | Effect | Example |
+|---|---|---|
+| `@` | Attach file content (fuzzy resolved) | `look at @src/api/auth.ts` |
+| `!` | Run shell, inject output | `!git diff` then ask about it |
+
+```text
+> review @packages/api/src/handlers/auth.ts for missing input validation
+> !pnpm test --reporter=verbose
+> based on those failures, fix the auth handler
+```
+
+#### `AGENTS.md` for project rules
+
+```markdown
+# AGENTS.md
+
+## Commands
+- build: `pnpm build`
+- test: `pnpm test`
+- lint: `pnpm lint && pnpm typecheck`
+
+## Conventions
+- TypeScript strict mode, no `any`
+- Prefer named exports; default exports only for React components
+
+## Don't
+- Edit anything under `vendor/`
+- Run migrations without confirmation
+- Push to `main` directly
+```
+
+Reads on every session. Add extra files via `instructions: ["..."]` in `opencode.json`.
+
+---
+
+### TUI & Themes
+
+#### Leader key
+
+OpenCode's TUI uses a **leader key** (default `ctrl+x`) followed by a single letter. Keeps single-keystroke editing keys free for the input box.
+
+| Binding | Action |
+|---|---|
+| `ctrl+x n` | New session |
+| `ctrl+x l` | List sessions |
+| `ctrl+x c` | Compact session |
+| `ctrl+x e` | Open external editor |
+| `ctrl+x m` | Browse models |
+| `ctrl+x t` | Switch theme |
+| `ctrl+x u` / `ctrl+x r` | Undo / Redo |
+| `ctrl+x q` | Quit |
+| `ctrl+p` | Command palette |
+| `Tab` | Cycle primary agents |
+| `Esc` | Cancel / dismiss |
+
+Readline shortcuts also work inside the prompt box (`ctrl+a`, `ctrl+e`, `ctrl+k`, `ctrl+u`).
+
+#### Themes
+
+Built-in: `system` Β· `tokyonight` Β· `everforest` Β· `ayu` Β· `catppuccin` Β· `catppuccin-macchiato` Β· `gruvbox` Β· `kanagawa` Β· `nord` Β· `matrix` Β· `one-dark`. Set via `/themes` or `tui.json`.
+
+```json
+{
+ "$schema": "https://opencode.ai/tui.json",
+ "theme": "tokyonight",
+ "leader_timeout": 2000,
+ "keybinds": { "command_list": "ctrl+p" }
+}
+```
+
+Custom themes: `.opencode/themes/.json` (project) or `~/.config/opencode/themes/.json` (global). Truecolor terminals required.
+
+> π Deep dive: [`docs/tui.md`](docs/tui.md) Β· [opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds) Β· [opencode.ai/docs/themes](https://opencode.ai/docs/themes).
+
+---
+
+### Headless & CI
+
+Three ways to run OpenCode unattended:
+
+```bash
+# 1. One-shot prompts
+opencode run "summarize the last 5 commits"
+opencode run --format json "list every TODO with file and line" > todos.json
+opencode run --agent plan --model anthropic/claude-haiku-4-5 \
+ "audit src/ for missing input validation"
+
+# 2. Headless server / web UI
+opencode serve --port 4096 --hostname 0.0.0.0
+opencode web --port 4096
+
+# 3. GitHub agent
+opencode github install # add a workflow file to your repo
+opencode pr 123 # check out PR #123 and start a session
+```
+
+Useful `run` flags: `--continue` / `--session ` (resume), `--share` (publish), `--format json` (machine-readable), `--file ` (attach), `--dangerously-skip-permissions` (auto-approve everything not `deny` β **CI only**).
+
+Sessions, stats, sharing:
+
+```bash
+opencode session list # past sessions
+opencode stats --days 30 --models # token & cost by model
+opencode export --sanitize # JSON dump (with redaction)
+opencode import session.json # restore from JSON or share URL
+```
+
+> π Full CLI reference: [`docs/reference/cli.md`](docs/reference/cli.md). CI recipes (GitHub Actions, GitLab CI): [`docs/workflows.md`](docs/workflows.md).
+
+---
+
+### Sharing
+
+`/share` generates a public link to the current session (`opncd.ai/s/`). Three modes via `opencode.json`:
+
+```json
+{ "share": "manual" } // default β only when you ask
+{ "share": "auto" } // every new session is shared
+{ "share": "disabled" } // forbid sharing entirely
+```
+
+`/unshare` revokes the link. Enterprise builds can enforce `"disabled"` via managed config.
+
+> β οΈ **Privacy:** Shared conversations live on OpenCode's servers until you unshare. Don't share sessions with secrets, proprietary code, or confidential data.
+
+---
+
+## Extending OpenCode
+
+OpenCode has **five extension points**. Pick by trigger and surface:
```mermaid
flowchart TD
@@ -43,383 +409,48 @@ flowchart TD
Q3 -->|External tool| MCP[MCP Server
opencode.json β mcp]
```
-Same information as a table:
-
-| Tool | Use when⦠| Skip if⦠| Lives in |
-|---|---|---|---|
-| **[Custom Commands](#custom-commands)** *(slash commands)* | You repeat the same prompt or workflow β₯3 times | One-off task | `.opencode/commands/*.md` |
-| **[Agent Skills](#agent-skills)** | You want OpenCode to **auto-discover** and load a workflow when the description matches | You only want manual invocation | `.opencode/skills//SKILL.md` |
-| **[Plugins](#plugins)** | You want JS/TS code to run **automatically** on events (tool calls, file edits, session lifecycle) | You only want chat-driven extensions | `.opencode/plugins/*.{js,ts}` |
-| **[Subagents](#subagents)** | A subtask is big or context-heavy enough to need its own session | The task fits in your main session | `.opencode/agents/.md` *(mode: `subagent`)* |
-| **[MCP servers](#model-context-protocol-mcp)** | You need OpenCode to use **external** tools (browsers, DBs, APIs, search) | All your data is in local files | `opencode.json` β `mcp` |
+| Extension | Triggered by | Lives in |
+|---|---|---|
+| [Custom Commands](#custom-commands) | User typing `/` | `.opencode/commands/*.md` |
+| [Agent Skills](#agent-skills) | Model auto-discovery (description match) | `.opencode/skills//SKILL.md` |
+| [Plugins](#plugins) | Lifecycle events (tool calls, file edits, sessions) | `.opencode/plugins/*.{js,ts}` |
+| [Agents](#agents) | Tab key or `@` mention | `.opencode/agents/.md` |
+| [MCP Servers](#mcp-servers) | Prompt-driven external tool use | `opencode.json` β `mcp` |
> π‘ These five compose. Most polished workflows combine 2β3.
---
-## π What's inside
-
-The README is the orientation. Deep dives live under [`docs/`](docs/); references under [`docs/reference/`](docs/reference/). Drop-in role prompts live under [`specialized-agents/`](specialized-agents/), MCP walkthroughs under [`mcp-servers/`](mcp-servers/), and a worked example of a configured project under [`.opencode/`](.opencode/).
-
-| Topic | In the README | Deep dive |
-|---|---|---|
-| **Fundamentals** | [What is OpenCode?](#what-is-opencode) Β· [Setup](#opencode-setup) Β· [Prompt Engineering](#prompt-engineering-deep-dive) | [`docs/quickstart.md`](docs/quickstart.md) |
-| **Provider & models** | [OpenCode Zen](#opencode-zen) Β· [Configuring providers](#configuring-providers) | [`docs/zen.md`](docs/zen.md) |
-| **Workflow extensions** | [Slash Commands](#slash-commands) Β· [Custom Commands](#custom-commands) Β· [Agent Skills](#agent-skills) Β· [Plugins](#plugins) | [`docs/commands.md`](docs/commands.md) Β· [`docs/skills.md`](docs/skills.md) Β· [`docs/plugins.md`](docs/plugins.md) |
-| **Multi-agent & integration** | [Subagents](#subagents) Β· [Custom Agents](#custom-agents) Β· [MCP](#model-context-protocol-mcp) | [`docs/agents.md`](docs/agents.md) Β· [`docs/mcp.md`](docs/mcp.md) |
-| **Productivity & runtime** | [TUI Mastery](#tui-mastery) Β· [Themes](#themes) Β· [Headless & CI](#headless--ci-usage) Β· [Sharing](#sharing) | [`docs/tui.md`](docs/tui.md) Β· [`docs/workflows.md`](docs/workflows.md) |
-| **Migration** | β | [`docs/migration.md`](docs/migration.md) *(Claude Code Β· Cursor Β· Copilot Β· Aider)* |
-| **Reference** | [FAQ](#faq) Β· [Updates & Deprecations](#updates--deprecations) Β· [Further Reading](#references) | [CLI](docs/reference/cli.md) Β· [Slash commands](docs/reference/slash-commands.md) Β· [Permissions](docs/reference/permissions.md) Β· [Full FAQ](docs/reference/faq.md) Β· [Changelog](docs/reference/changelog.md) Β· [Further reading](docs/reference/further-reading.md) |
-
----
-
-### 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. It's maintained by [Anomaly](https://github.com/anomalyco) and shipped under the MIT license.
-
-**Three things it does that a chat UI can't:**
-
-- **Reads your actual repo** β not pasted snippets. It greps your files, follows imports, and grounds answers in real context using built-in `read`/`grep`/`glob` tools.
-- **Edits in place and runs your stack** β diff-aware `edit`/`write`/`apply_patch`, then `bash` to run your tests, linter, or build on the spot.
-- **Composes with the rest of your toolchain** β multi-provider models, custom slash commands, agent skills, JS/TS plugins, MCP servers, LSP, formatters, and an HTTP server for CI use.
-
-**Three interfaces:**
-
-| Surface | Command | When |
-|---|---|---|
-| **TUI** (default) | `opencode` | Interactive day-to-day work in your terminal |
-| **CLI / headless** | `opencode run ""` | Scripts, CI jobs, one-shot prompts |
-| **Server** | `opencode serve` or `opencode web` | Headless API, web UI, or remote attach |
-
-```bash
-opencode # start TUI in the current repo
-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. OpenCode is provider-agnostic and open source; Claude Code is tightly integrated with Anthropic; Cursor embeds in a VS Code fork; Aider is leaner and Python-based. None is universally better β pick the one whose model, surface, and ecosystem fit your workflow.
-
-> β οΈ **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.
-
----
-
-### OpenCode Setup
-
-> β±οΈ **5-minute setup.** From zero to your first AI-assisted commit.
-
-#### 1. Install
-
-```bash
-curl -fsSL https://opencode.ai/install | bash
-```
-
-Other supported installers (pick whichever you already use):
-
-```bash
-npm i -g opencode-ai@latest # npm / pnpm / yarn / bun all work
-brew install anomalyco/tap/opencode # macOS / Linux
-brew install opencode # if you've added the tap
-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
-nix run nixpkgs#opencode # Nix
-```
-
-A desktop app for macOS / Windows / Linux is in beta at [opencode.ai/download](https://opencode.ai/download).
-
-> π The full install matrix (including Windows/WSL, Docker, enterprise managed configs) lives at [opencode.ai/docs](https://opencode.ai/docs).
-
-#### 2. Authenticate
-
-Run `opencode` and use `/connect` from the TUI, or sign in from the CLI:
-
-```bash
-opencode auth login # interactive provider picker
-opencode auth list # see who you're signed in to
-```
-
-You can point OpenCode at:
-
-- **Direct providers** β Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure, Ollama, LM Studio, and more (full list at [opencode.ai/docs/providers](https://opencode.ai/docs/providers)). Best if you already have credits with a provider or want to run locally.
-- **[OpenCode Zen](#opencode-zen)** β pay-as-you-go gateway curated by the OpenCode team. Best if you want one key and a vetted lineup; pricier per token than going direct in some cases.
-- **Local models** via Ollama or LM Studio. Best for offline work or strict data-residency requirements; quality varies widely by model and hardware.
-
-There's no "right" default β pick what fits your existing accounts, budget, and privacy posture.
-
-#### 3. First prompt
-
-From any project directory:
-
-```bash
-cd ~/your-project
-opencode
-```
-
-Try one of these once the TUI is up:
-
-- `explain what this codebase does` β OpenCode reads your repo and summarizes.
-- `add a README section about installation` β generates content based on what's already there.
-- `find and fix the failing test in src/api.test.ts` β diagnoses and edits in place.
-
-#### 4. Generate an `AGENTS.md`
-
-```
-/init
-```
-
-`/init` walks you through generating an `AGENTS.md` file β your project's "house rules" that OpenCode reads every session (build/test commands, conventions, architecture). Commit it to git. More in [Prompt Engineering Deep Dive](#prompt-engineering-deep-dive).
-
-> π **Coming from Claude Code?** OpenCode reads `CLAUDE.md` as a fallback if no `AGENTS.md` exists. Migrate by renaming the file or letting `/init` generate a fresh one. Disable the fallback with `OPENCODE_DISABLE_CLAUDE_CODE=1`.
-
-#### 5. (Bonus) See a real OpenCode project setup
-
-This repo's own [`.opencode/`](.opencode/) directory is a working example of a fully-configured project. Browse it as a reference:
-
-| Path | What it does |
-|---|---|
-| [`.opencode/agents/`](.opencode/agents) | Custom agent definitions (markdown + YAML frontmatter) |
-| [`.opencode/commands/`](.opencode/commands) | Custom slash commands β invoke with `/` |
-| [`.opencode/skills/`](.opencode/skills) | Auto-discovered agent skills with `SKILL.md` files |
-| [`AGENTS.md`](AGENTS.md) | Project instructions OpenCode reads every session |
-
-> π‘ **Next:** Once you're comfortable with the basics, jump to [Custom Commands](#custom-commands) to build reusable slash commands in 3 minutes.
-
----
-
-### OpenCode Zen
-
-> **Mental model:** Zen is OpenCode's curated, pay-as-you-go model gateway β a hand-picked roster of models the OpenCode team has tested and tuned for coding-agent workloads. One API key, dozens of models, billing in cents.
-
-#### Setup
-
-```bash
-# 1. Visit https://opencode.ai/auth and create an account
-# 2. Add billing details
-# 3. Copy your API key
-# 4. In OpenCode:
-/connect # pick "OpenCode Zen" and paste your key
-/models # browse what's available
-```
-
-Reference Zen models in `opencode.json` or `/model` using the `opencode/` namespace.
-
-#### Pricing snapshot (verified May 2026)
-
-> Always check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) β prices change.
-
-> Model IDs use the format `opencode/` in your config. Slugs preserve dots where the upstream model uses them (e.g. `gpt-5.5`, `gemini-3.1-pro`); Anthropic IDs use hyphens (`claude-opus-4-7`).
-
-| Model ID | Input / Output (per MTok) | Reach for it when⦠|
-|---|---|---|
-| `opencode/claude-opus-4-7` | $5 / $25 | Complex reasoning, large refactors, multi-file analysis |
-| `opencode/claude-sonnet-4-6` | $3 / $15 | Balanced everyday coding β the workhorse |
-| `opencode/claude-haiku-4-5` | $1 / $5 | Fast, lightweight tasks β quick questions, doc edits |
-| `opencode/gpt-5.5` *(β€272K)* | $5 / $30 | Long-context work, OpenAI ecosystem |
-| `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/gemini-3.1-pro` | $2 / $12 | Multimodal, Google ecosystem |
-| `opencode/qwen3.6-plus` | $0.50 / $3 | Budget-friendly heavy lifting |
-
-**Free tier** *(rotating, for community feedback):* `deepseek-v4-flash-free`, `minimax-m2.5-free`, `nemotron-3-super-free`, `big-pickle` *(stealth)*. Great for learning without burning credits.
-
-> Full model list (40+ entries with per-model pricing including cached read/write, GPT 5 Codex variants, GLM, Kimi, Claude Opus 4.5/4.6/4.1, etc.): [opencode.ai/docs/zen](https://opencode.ai/docs/zen).
-
-#### Billing & limits
-
-- **Auto-reload** β default $20 top-up when balance falls under $5. Configurable.
-- **Workspaces** β monthly spending caps for teams; per-member limits available.
-- **BYOK** β bring your own Anthropic / OpenAI keys and still use Zen for other providers.
-- **Transaction fees** β credit card fees pass through at cost (4.4% + $0.30 per transaction).
-
-> π‘ **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.
-
----
-
-### Configuring providers
-
-If Zen isn't your thing, OpenCode talks to providers directly. Configuration lives in `opencode.json` (project-level) or `~/.config/opencode/opencode.json` (global). Both JSON and JSONC (comments) are supported.
-
-```json
-{
- "$schema": "https://opencode.ai/config.json",
- "model": "anthropic/claude-sonnet-4-5",
- "provider": {
- "anthropic": {
- "options": {
- "apiKey": "{env:ANTHROPIC_API_KEY}"
- }
- },
- "openai": {
- "options": {
- "apiKey": "{file:~/.secrets/openai-key}"
- }
- }
- }
-}
-```
-
-**Variable substitution:**
-
-- `{env:NAME}` β pulls from the environment
-- `{file:./path}` β reads from a local file (absolute or relative)
-
-**Per-agent model override:**
-
-```json
-{
- "agent": {
- "plan": { "model": "anthropic/claude-haiku-4-5" },
- "deep-thinker": {
- "model": "openai/gpt-5",
- "reasoningEffort": "high"
- }
- }
-}
-```
-
-> π Full config reference: [opencode.ai/docs/config](https://opencode.ai/docs/config) β includes `enabled_providers`, `disabled_providers`, formatter integration, LSP, watcher ignores, attachment limits, and more.
-
----
-
-### Prompt Engineering Deep Dive
-
-> **π Project Initialization**
-> Run `/init` to auto-generate an `AGENTS.md`. Treat it like any frequently used prompt β iterate on it. Don't just dump 500 lines and forget; refine what produces the best follow-through from the model.
-
-#### 1. Plan β Build cycle
-
-OpenCode ships with two primary agents you can toggle between with **Tab**:
-
-| Agent | What changes | Use it for |
-|---|---|---|
-| **`plan`** | `edit` and `bash` permissions default to `ask` β analysis without surprise writes | Reading code, designing approaches, reviewing diffs |
-| **`build`** | Full tool access (default) | Implementation, refactors, running tests |
-
-The natural workflow is **explore in plan, switch to build, commit**:
-
-```text
-[plan] > how would you implement OAuth for this app?
- (OpenCode reads, plans, proposes β no writes happen)
-[plan] >
-[build] > do it
- (OpenCode implements, edits files, runs tests)
-```
-
-> π‘ **Pro Tip:** Research and plan first. For complex changes, prompts like `think hard`, `think more`, or `ultrathink` nudge depth on supported models β exactly the pattern the [Anthropic prompt engineering guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) recommends.
-
-#### 2. Test-Driven Workflow
-
-Ideal for changes verifiable with unit or integration tests.
-
-```text
-[plan] > write failing tests for a `slugify` util that handles unicode, spaces, and trailing punctuation
-[build] > run the tests β confirm they fail
-[build] > implement slugify so the tests pass
-[build] > /share (optional: capture the session)
-```
-
-Clear, executable targets (tests, mocks) drive iteration far more reliably than prose specs.
-
-#### 3. File references and shell
-
-Two characters that change how you talk to OpenCode:
-
-| Syntax | What it does | Example |
-|---|---|---|
-| `@` | Attach file content to the prompt (fuzzy search) | `look at @src/api/auth.ts` |
-| `!` | Run shell and inject the output | `!git diff` then ask Claude about it |
-
-```text
-> review @packages/api/src/handlers/auth.ts for missing input validation
-> !pnpm test --reporter=verbose
-> based on those failures, fix the auth handler
-```
-
-#### 4. Use `AGENTS.md` for project rules
-
-```markdown
-# AGENTS.md
-
-## Commands
-- build: `pnpm build`
-- test: `pnpm test`
-- lint: `pnpm lint && pnpm typecheck`
-
-## Conventions
-- TypeScript strict mode, no `any`
-- Prefer named exports; default exports only for React components
-- Tailwind first; CSS modules only for legacy code
-
-## Don't
-- Edit anything under `vendor/`
-- Run migrations without confirmation
-- Push to `main` directly
-```
-
-OpenCode reads `AGENTS.md` from the project root on every session start. Additional instruction files can be referenced via the `instructions` key in `opencode.json`:
-
-```json
-{
- "instructions": ["CONTRIBUTING.md", "docs/style-guide.md", ".cursor/rules/*.md"]
-}
-```
-
-> π Full guide: [opencode.ai/docs/rules](https://opencode.ai/docs/rules).
-
----
-
### Slash Commands
OpenCode ships a set of built-in slash commands plus everything you write yourself.
-#### Built-in essentials
-
| Command | What it does |
|---|---|
| `/init` | Guided generation of `AGENTS.md` |
| `/help` | Show the help dialog |
-| `/new` *(alias `/clear`)* | Start a new session |
-| `/sessions` *(aliases `/resume`, `/continue`)* | List and switch between sessions |
-| `/models` | Browse available models |
+| `/new` *(`/clear`)* | New session |
+| `/sessions` *(`/resume`, `/continue`)* | List and switch sessions |
+| `/models` | Browse models |
| `/connect` | Add a provider |
-| `/themes` | Switch themes |
-| `/compact` *(alias `/summarize`)* | Compact the current session to save tokens |
-| `/share` Β· `/unshare` | Create or revoke a public link to the session |
-| `/export` | Export conversation to Markdown |
-| `/undo` Β· `/redo` | Step through edit history |
-| `/editor` | Open `$EDITOR` to compose a long prompt |
-| `/details` | Toggle visibility of tool execution details |
-| `/thinking` | Toggle thinking/reasoning blocks |
-| `/exit` *(aliases `/quit`, `/q`)* | Quit OpenCode |
+| `/themes` | Switch theme |
+| `/compact` *(`/summarize`)* | Compact session to save tokens |
+| `/share` Β· `/unshare` | Public link control |
+| `/export` | Export to markdown |
+| `/undo` Β· `/redo` | Walk edit history |
+| `/editor` | Open `$EDITOR` |
+| `/details` Β· `/thinking` | Toggle visibility of tool / reasoning blocks |
+| `/exit` *(`/quit`, `/q`)* | Exit |
-> π Full slash-command reference: [`docs/reference/slash-commands.md`](docs/reference/slash-commands.md). Built-in commands can be overridden by your own custom commands with the same name.
+Custom commands can override built-ins with the same name.
-#### Custom slash commands β the 30-second version
-
-Save a prompt as a markdown file in `.opencode/commands/`, invoke it forever:
-
-```bash
-mkdir -p .opencode/commands
-cat > .opencode/commands/optimize.md << 'EOF'
----
-description: Suggest performance improvements
----
-Analyze the current code for performance bottlenecks. Propose specific,
-measurable optimizations with before/after snippets.
-EOF
-
-opencode # then type: /optimize
-```
-
-β Deep dive in [Custom Commands](#custom-commands).
+> π Full reference: [`docs/reference/slash-commands.md`](docs/reference/slash-commands.md).
---
### Custom Commands
-> **Mental model:** A custom command is a prompt template you've named. Whatever you save as `.opencode/commands/.md` becomes `/` in the TUI β with `$ARGUMENTS`, `@file`, and `!shell` placeholders interpolated at invocation time.
+> **Mental model:** A custom command is a prompt template you've named. Save as `.opencode/commands/.md`, invoke as `/` in the TUI β with `$ARGUMENTS`, `@file`, and `!shell` interpolated at invocation time.
Minimal example:
@@ -435,24 +466,24 @@ If any tests failed above, open the failing files and propose precise fixes.
Otherwise, summarize the coverage.
```
-Save as `.opencode/commands/test.md` β invoke with `/test` in the TUI.
+Save as `.opencode/commands/test.md` β invoke with `/test`.
| Frontmatter key | Purpose |
|---|---|
-| `description` (required) | One-liner shown in the slash-command palette |
-| `agent` | Which agent runs it (`build`, `plan`, or a custom one) |
+| `description` (required) | Shown in the slash-command palette |
+| `agent` | Which agent runs it (`build`, `plan`, or custom) |
| `model` | Override the model just for this command |
-| `subtask` | `true` runs as a subagent (isolated context) |
+| `subtask` | `true` runs as a subagent (isolated child session) |
| Body placeholder | Substitutes |
|---|---|
-| `$ARGUMENTS` / `$1` / `$2` | What the user typed after the command |
+| `$ARGUMENTS` / `$1` / `$2` | Text after the command name |
| `@` | File content (fuzzy resolved) |
| `` `!` `` | Shell stdout |
-**This repo ships four examples in [`.opencode/commands/`](.opencode/commands/):** `/review`, `/pr`, `/test`, `/optimize`.
+This repo ships four examples in [`.opencode/commands/`](.opencode/commands/): `/review`, `/pr`, `/test`, `/optimize`.
-> π Deep dive β frontmatter, body placeholders, override patterns, gotchas: [`docs/commands.md`](docs/commands.md) and [opencode.ai/docs/commands](https://opencode.ai/docs/commands).
+> π Deep dive: [`docs/commands.md`](docs/commands.md) Β· [opencode.ai/docs/commands](https://opencode.ai/docs/commands).
---
@@ -460,7 +491,7 @@ Save as `.opencode/commands/test.md` β invoke with `/test` in the TUI.
> **Mental model:** A skill is a **discoverable** workflow. The agent sees the skill's `name` and `description` and decides on its own to load it when the task matches. You don't have to remember to invoke β the model does.
-OpenCode uses Claude Code-compatible Agent Skill folders. Skill lookup paths (project β global β Claude-compatible β agent-compatible):
+OpenCode uses Claude Code-compatible Agent Skill folders. Lookup paths (project β global β Claude-compat β Agent-compat):
```
.opencode/skills//SKILL.md
@@ -469,129 +500,70 @@ OpenCode uses Claude Code-compatible Agent Skill folders. Skill lookup paths (pr
.agents/skills//SKILL.md
```
-Each `SKILL.md` needs YAML frontmatter with a `name` (lowercase-kebab, β€64 chars) and a `description` (1β1024 chars). The description is **the discovery signal** β write it like a trigger sentence the agent will recognize.
+Each `SKILL.md` needs YAML frontmatter with a `name` (lowercase-kebab, β€64 chars) and a `description` (1β1024 chars). **The description is the discovery signal** β write it like a trigger sentence the agent will recognize.
**Command vs. skill, in one line:** commands are user-invoked (`/`), skills are model-invoked (description match). Write both for the same workflow if you want both surfaces.
-**This repo ships one example:** [`.opencode/skills/git-release/SKILL.md`](.opencode/skills/git-release/SKILL.md).
+This repo ships one example: [`.opencode/skills/git-release/SKILL.md`](.opencode/skills/git-release/SKILL.md).
-> π Deep dive β discovery patterns, permission gating, writing descriptions models actually pick up: [`docs/skills.md`](docs/skills.md) and [opencode.ai/docs/skills](https://opencode.ai/docs/skills).
+> π Deep dive: [`docs/skills.md`](docs/skills.md) Β· [opencode.ai/docs/skills](https://opencode.ai/docs/skills).
---
### Plugins
-> **Mental model:** Plugins are OpenCode's **lifecycle hooks** β small JavaScript/TypeScript modules that subscribe to events (tool calls, file edits, session state) and run code automatically. Think `husky`/`lefthook` for your AI session.
+> **Mental model:** Plugins are OpenCode's **event-driven extension surface** β small JavaScript or TypeScript modules that subscribe to lifecycle events (tool calls, file edits, session state) and run code automatically. `husky` for your AI session.
-#### Where plugins live
+Two locations:
-| Scope | Path |
-|---|---|
-| Project | `.opencode/plugins/.{js,ts}` |
-| Global | `~/.config/opencode/plugins/.{js,ts}` |
-| NPM packages | `plugin` array in `opencode.json` |
+```
+.opencode/plugins/.{js,ts} # project
+~/.config/opencode/plugins/.{js,ts} # global
+```
-NPM-installed plugins:
+Plus npm packages via the `plugin` array in `opencode.json`:
```json
-{
- "plugin": [
- "opencode-helicone-session",
- "opencode-wakatime",
- "@my-org/custom-plugin"
- ]
-}
+{ "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"] }
```
-These auto-install via Bun and cache under `~/.cache/opencode/node_modules/`.
+Auto-installed via Bun, cached under `~/.cache/opencode/node_modules/`.
-Local plugins can use npm dependencies β drop a `package.json` next to them.
+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.
-#### Plugin API
-
-```javascript
-export const NotifyOnSessionIdle = async ({ project, client, $, directory, worktree }) => {
- return {
- event: async ({ event }) => {
- if (event.type === "session.idle") {
- await $`osascript -e 'display notification "Session done!" with title "opencode"'`;
- }
- },
- };
-};
-```
-
-Plugins receive a context object `{ project, directory, worktree, client, $ }` and return event handlers. `$` is the Bun shell β run any command from inside the plugin. Events span tools, files, sessions, messages, permissions, LSP, TUI, and more (~25 in total).
-
-**This repo ships two working examples in [`.opencode/plugins/`](.opencode/plugins/):**
+This repo ships two working examples in [`.opencode/plugins/`](.opencode/plugins/):
| File | What it does |
|---|---|
-| [`protect-secrets.js`](.opencode/plugins/protect-secrets.js) | Blocks any tool call touching `.env*`, `secrets/`, SSH keys, etc. |
+| [`protect-secrets.js`](.opencode/plugins/protect-secrets.js) | Blocks any tool call touching `.env*`, `secrets/`, SSH keys |
| [`audit-log.js`](.opencode/plugins/audit-log.js) | Appends every successful tool call to `.opencode/audit.jsonl` |
-> β οΈ **Security:** Plugins run arbitrary code with your user permissions. Read every third-party plugin before installing β exactly like reviewing a shell script before sourcing it.
+> β οΈ **Security:** Plugins run arbitrary code with your user permissions. Read every third-party plugin before installing β exactly like reviewing a shell script before sourcing.
-> π Deep dive β full event list, hook patterns (auto-format on save, idle notifications, sensitive-path blocking, audit logging), and gotchas: [`docs/plugins.md`](docs/plugins.md) and [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
+> π Deep dive: [`docs/plugins.md`](docs/plugins.md) Β· [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
---
-### Subagents
+### Agents
-> **Mental model:** Subagents are **child sessions** spawned from your main session ([docs](https://opencode.ai/docs/agents#usage)). Each runs separately with its own focused scope and tool surface, so the main session doesn't have to carry their full conversation. Navigate between parent and children with the `session_child_*` keybinds (default: `+β/β/β/β`).
+OpenCode ships five built-in agents, and you can define your own as markdown files.
-#### Built-in subagents
+#### Built-in
-| Subagent | Tools | Reach for it when⦠|
-|---|---|---|
-| **`general`** | Full toolset (minus `todowrite`) | Multi-step tasks you want isolated from the main session |
-| **`explore`** | Read-only β `read`, `grep`, `glob`, `list` | "Where is X defined?" or quick code searches |
-| **`scout`** | Read-only β `webfetch`, `websearch`, plus read tools | External docs and dependency research |
+| Agent | Mode | Tools | Reach for it when⦠|
+|---|---|---|---|
+| `build` | primary (default) | All | Default daily-driver β implementation, refactors |
+| `plan` | primary | `edit` and `bash` default to `ask` | Read-only-ish analysis, exploration |
+| `general` | subagent | All minus `todowrite` | Multi-step tasks isolated from main session |
+| `explore` | subagent | `read`, `grep`, `glob`, `list` | "Where is X?" code search |
+| `scout` | subagent | `webfetch`, `websearch`, + read tools | External docs and dependency research |
-Invoke them by `@`-mentioning from your main session:
+`Tab` cycles primaries. `@` invokes a subagent.
-```text
-@explore Find every call site of `parseToken()` and summarize the patterns
-@scout What does the new Stripe SDK v15 say about idempotency keys?
-@general Refactor src/auth/ so OAuth and JWT flows share a single token service
-```
-
-#### Custom subagents
+#### Custom
Drop a markdown file in `.opencode/agents/`:
-```markdown
----
-description: Performs security audits and flags vulnerabilities
-mode: subagent
-model: anthropic/claude-sonnet-4-5
-temperature: 0.1
-permission:
- edit: deny
- bash: deny
----
-
-You are a security reviewer. Focus on OWASP Top 10 issues, secret leaks,
-input validation, authentication, and authorization. Surface findings with:
-- Severity (critical / high / medium / low)
-- File and line
-- Why it's a problem
-- A concrete fix
-Do not modify files β your job is to report.
-```
-
-The filename becomes the agent name. `security-auditor.md` β `@security-auditor`.
-
-β Full agent definition format and permission system in [Custom Agents](#custom-agents).
-
----
-
-### Custom Agents
-
-Beyond subagents, you can define **primary agents** (`mode: primary` or `mode: all`) β your own variants of `build` and `plan` with custom prompts, models, and permission profiles. Same markdown-with-YAML-frontmatter format as subagents.
-
-Minimal example:
-
```markdown
---
description: Senior frontend engineer β Tailwind + React + TypeScript
@@ -608,27 +580,27 @@ permission:
You're a senior frontend engineer working on a React/Tailwind codebaseβ¦
```
-Filename β agent name. `frontend-engineer.md` β invoked as `@frontend-engineer` (subagent) or in the Tab cycle (primary). The mode determines surfaces:
+Filename β agent name. `frontend-engineer.md` β `@frontend-engineer` (subagent) or in the Tab cycle (primary). The `mode` value picks the surface:
| `mode` | Where it appears |
|---|---|
-| `primary` | Tab-cycle alongside `build`/`plan` |
-| `subagent` | `@` mentions only |
+| `primary` | Tab cycle alongside `build` / `plan` |
+| `subagent` | `@` 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.
> π 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/.md` to use.
-> π Deep dive β full frontmatter key list, permission model with all 16 keys, JSON-form alternative, picking a model per agent: [`docs/agents.md`](docs/agents.md) Β· [`docs/reference/permissions.md`](docs/reference/permissions.md) Β· [opencode.ai/docs/agents](https://opencode.ai/docs/agents).
+> π 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).
---
-### Model Context Protocol (MCP)
+### MCP Servers
> MCP is the universal connector that lets OpenCode talk to **external tools** β browsers, databases, search engines, ticketing systems β through one open protocol. USB-C for AI integrations.
-Declare servers in the `mcp` section of `opencode.json`. Local servers spawn a subprocess; remote servers hit an HTTPS endpoint and handle OAuth automatically via Dynamic Client Registration (RFC 7591).
+Declare servers in the `mcp` section of `opencode.json`. Local servers spawn a subprocess; remote servers hit an HTTPS endpoint with automatic OAuth via Dynamic Client Registration (RFC 7591).
```json
{
@@ -654,7 +626,7 @@ Declare servers in the `mcp` section of `opencode.json`. Local servers spawn a s
Manage from the CLI: `opencode mcp add | list | auth | logout | debug `. Reference a server's tools in a prompt with `use `.
-**Featured walkthroughs in [`mcp-servers/`](./mcp-servers/):**
+Featured walkthroughs in [`mcp-servers/`](./mcp-servers/):
| Server | What it adds |
|---|---|
@@ -665,205 +637,30 @@ Manage from the CLI: `opencode mcp add | list | auth | logout | de
> β οΈ **Token budget:** MCP tools land in the model's tool surface every turn β heavy servers can easily eat 10K+ tokens of context. Disable noisy tools with the `tools` map (e.g. `"github_*": false`).
-> π Deep dive β local/remote config, OAuth flow, registry discovery, troubleshooting: [`docs/mcp.md`](docs/mcp.md) Β· [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers) Β· [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/).
+> π Deep dive: [`docs/mcp.md`](docs/mcp.md) Β· [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers) Β· [Registry](https://registry.modelcontextprotocol.io/).
---
-### TUI Mastery
-
-The TUI is where you'll spend most of your time. A few keys and patterns pay back the time it takes to learn them.
-
-#### Leader key
-
-OpenCode's TUI uses a **leader key** (default `ctrl+x`) followed by a single letter. It keeps single-keystroke editing keys free for the input box.
-
-| Binding | Action |
-|---|---|
-| `ctrl+x n` | New session |
-| `ctrl+x l` | List sessions |
-| `ctrl+x c` | Compact session |
-| `ctrl+x e` | Open external editor |
-| `ctrl+x m` | Browse models |
-| `ctrl+x t` | Switch theme |
-| `ctrl+x u` / `ctrl+x r` | Undo / Redo |
-| `ctrl+x b` | Toggle sidebar |
-| `ctrl+x y` | Copy messages |
-| `ctrl+x q` | Quit |
-| `ctrl+p` | Command palette |
-| `Tab` | Cycle primary agents (build β plan β custom) |
-| `Esc` | Cancel / dismiss |
-
-Readline shortcuts also work inside the prompt box:
-
-| Shortcut | Action |
-|---|---|
-| `ctrl+a` / `ctrl+e` | Beginning / end of line |
-| `ctrl+k` | Delete to end of line |
-| `ctrl+u` | Delete to beginning of line |
-
-#### Customizing keybinds
-
-Put a `tui.json` next to your `opencode.json`:
-
-```json
-{
- "$schema": "https://opencode.ai/tui.json",
- "leader_timeout": 2000,
- "keybinds": {
- "command_list": "ctrl+p",
- "messages_copy": ["y", "ctrl+shift+c"],
- "input_paste": { "key": "ctrl+v", "preventDefault": false }
- }
-}
-```
-
-Set any binding to `"none"` or `false` to disable it. Strings can be arrays for multiple bindings.
-
-> π Full keybind reference: [opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds).
-
----
-
-### Themes
-
-Built-in themes ship with OpenCode and can be set in `tui.json` or via `/themes`:
-
-`system` Β· `tokyonight` Β· `everforest` Β· `ayu` Β· `catppuccin` Β· `catppuccin-macchiato` Β· `gruvbox` Β· `kanagawa` Β· `nord` Β· `matrix` Β· `one-dark`
-
-```json
-{
- "$schema": "https://opencode.ai/tui.json",
- "theme": "tokyonight"
-}
-```
-
-**Custom themes** live in `.opencode/themes/.json` (project) or `~/.config/opencode/themes/.json` (global). Themes support hex (`"#ffffff"`), ANSI (0β255), references, dark/light variants, and `"none"` for terminal defaults. Truecolor terminals required.
-
-> π Full Themes guide: [opencode.ai/docs/themes](https://opencode.ai/docs/themes).
-
----
-
-### Headless & CI Usage
-
-OpenCode is built to run unattended. Three ways:
-
-#### 1. One-shot prompts (`opencode run`)
-
-```bash
-opencode run "summarize the changes in the last 5 commits"
-opencode run --format json "list every TODO comment with file and line" > todos.json
-opencode run --agent plan --model anthropic/claude-haiku-4-5 \
- "audit src/ for missing input validation"
-```
-
-Useful flags:
-
-| Flag | Purpose |
-|---|---|
-| `--continue` / `--session ` | Resume previous work |
-| `--share` | Publish the resulting session |
-| `--format json` | Machine-readable output |
-| `--file ` | Attach a file to the prompt |
-| `--dangerously-skip-permissions` | Auto-approve everything that isn't `deny` β **CI only** |
-
-#### 2. Headless server (`opencode serve` / `opencode web`)
-
-```bash
-opencode serve --port 4096 --hostname 0.0.0.0
-opencode web --port 4096 # same, with a browser UI
-```
-
-Talk to it via the OpenCode SDK or attach another terminal:
-
-```bash
-opencode attach http://localhost:4096
-```
-
-#### 3. GitHub agent
-
-```bash
-opencode github install # add a workflow file to your repo
-opencode github run # run locally with a mock event payload
-opencode pr 123 # check out PR #123 and start a session
-```
-
-The installed GitHub Action lets you `@`-mention the OpenCode bot on issues and PRs.
-
-#### Sessions, stats, sharing
-
-```bash
-opencode session list # browse past sessions
-opencode session delete # delete one
-opencode stats --days 30 --models # token & cost report by model
-opencode export --sanitize # JSON dump (with redaction)
-opencode import session.json # restore from JSON or share URL
-```
-
-> π Full CLI reference: [`docs/reference/cli.md`](docs/reference/cli.md).
-
----
-
-### Sharing
-
-`/share` generates a public link to the current session (`opncd.ai/s/`). Three modes via `opencode.json`:
-
-```json
-{ "share": "manual" } // default β only when you ask
-{ "share": "auto" } // every new session is shared
-{ "share": "disabled" } // forbid sharing entirely
-```
-
-`/unshare` revokes the link. Enterprise builds can enforce `"disabled"` from a managed config so it's not bypassable.
-
-> β οΈ **Privacy:** Shared conversations live on OpenCode's servers until you unshare them. Don't share sessions with secrets, proprietary code, or confidential data.
-
-> π Full Sharing guide: [opencode.ai/docs/share](https://opencode.ai/docs/share).
-
----
-
-### Limitations & when OpenCode isn't the right tool
-
-Useful tools have honest weaknesses. OpenCode's:
-
-| Limitation | Detail |
-|---|---|
-| **No inline editor completion** | OpenCode is a conversational agent, not a Copilot-style autocomplete. If your main pain is "ghost text while I type," reach for [Copilot](https://github.com/features/copilot), [Cursor Tab](https://cursor.sh/), [Codeium](https://codeium.com/), or [Supermaven](https://supermaven.com/) instead β or alongside. |
-| **Quality depends on the underlying model** | OpenCode doesn't replace the LLM's reasoning. If your task fails on Claude Sonnet, switching to OpenCode won't magically fix it. |
-| **Provider-agnostic β provider-equivalent** | Some models work better with OpenCode's tool-use loop than others. Don't assume a slug swap is free. |
-| **TUI on slow SSH / minimal terminals** | The TUI uses truecolor and complex layouts. Over a slow connection or a terminal that doesn't support 24-bit color, the experience degrades. `opencode serve` + `attach` helps; the desktop app or `opencode run` may be better for those cases. |
-| **Plugins run arbitrary code** | Any plugin you install β local or npm β has full user permissions. Audit before installing. |
-| **Free Zen models are explicitly time-limited** | The [Zen docs](https://opencode.ai/docs/zen) describe them as "available on OpenCode for a limited time" while the team collects feedback. Don't build production workflows around them. |
-| **Documentation lags shipping** | OpenCode moves fast. This guide and even the official docs occasionally trail the actual binary. Run `opencode --version` and check release notes when something doesn't behave as documented. |
-| **Not a substitute for code review** | Diff-aware edits and a passing test suite don't guarantee correct, secure, or maintainable code. Treat AI output as a junior teammate's PR: useful, not authoritative. |
-
-**When OpenCode might be the wrong choice for you:**
-
-- You want a polished, opinionated single-vendor product where everything just works β **Claude Code** or **Cursor** will feel more cohesive.
-- You're deeply embedded in a VS Code workflow and want AI features inside the IDE β **Cursor** or **GitHub Copilot** integrates more tightly.
-- You want a small, focused, well-understood Python tool you can read end-to-end β **[Aider](https://aider.chat/)** is leaner.
-- You don't want to manage provider keys or configs at all β a hosted product with a managed billing flow may suit you better.
-
-> The trade-off OpenCode makes: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.
-
----
+## Reference
### FAQ
*[β 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; bring your own Anthropic/OpenAI/Google key if you prefer.
+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.
**Does OpenCode work without an internet connection?**
-Yes, if you point it at a local model (Ollama, LM Studio, llama.cpp). Network is needed for hosted providers, MCP remote servers, sharing, and updates.
+Yes, with a local model (Ollama, LM Studio, llama.cpp). Network is needed for hosted providers, remote MCP servers, sharing, and updates.
**Can I migrate from Claude Code?**
-Most concepts map cleanly but a few fields and file paths differ. OpenCode reads `CLAUDE.md` as a fallback for `AGENTS.md` and `.claude/skills//SKILL.md` for skills (so half your config keeps working untouched). Slash commands need to move from `.claude/commands/` to `.opencode/commands/`; Python hooks need to be rewritten as JS/TS plugins; subagent frontmatter uses different field names (`name` is gone, `mode` is new, `tools` becomes `permission`). See [the full migration guide](docs/migration.md). Set `OPENCODE_DISABLE_CLAUDE_CODE=1` once you've migrated.
+Most concepts map cleanly but a few fields and file paths differ. OpenCode reads `CLAUDE.md` and `.claude/skills/` as fallbacks. Slash commands move from `.claude/commands/` β `.opencode/commands/`; Python hooks become JS/TS plugins; agent frontmatter uses different keys (`name` gone, `mode` new, `tools` becomes `permission`). See [the full migration guide](docs/migration.md).
**Custom commands vs. skills β which should I write?**
-Both. Custom commands are **explicit** (you type `/`); skills are **discoverable** (the model picks them up when the task matches). Use commands for workflows the user owns, skills for expertise the agent should reach for. See the comparison in [`docs/commands.md`](docs/commands.md#when-to-use-a-command-vs-a-skill-vs-an-agent).
+Both. Commands are **explicit** (user types `/`); skills are **discoverable** (model picks them up). Use commands for workflows the user owns, skills for expertise the agent should reach for. Comparison in [`docs/commands.md`](docs/commands.md#when-to-use-a-command-vs-a-skill-vs-an-agent).
**How do I keep OpenCode from running risky shell commands?**
-Set `bash` permission to `"ask"` at the project level (default for the `plan` agent already), or use the glob form to whitelist only safe patterns. Full mechanism in [`docs/reference/permissions.md`](docs/reference/permissions.md).
+Set `bash` permission to `"ask"` at the project level, or use the glob form to whitelist only safe patterns. Full mechanism in [`docs/reference/permissions.md`](docs/reference/permissions.md).
**Where do I see my token usage?**
`opencode stats` for a multi-day breakdown by model and project. The TUI also surfaces per-session totals in the footer.
@@ -874,27 +671,19 @@ Set `bash` permission to `"ask"` at the project level (default for the `plan` ag
*[β Full changelog in `docs/reference/changelog.md`](docs/reference/changelog.md)*
-**Current release:** **v1.15.4** *(May 17, 2026)*. Run `opencode upgrade` to get it.
+**Current release:** **v1.15.4** *(2026-05-17)*. Run `opencode upgrade` to get it.
-**Recent highlights (verified via [the OpenCode docs](https://opencode.ai/docs/)):**
+**Recent highlights:**
-- π **Agent Skills compatibility** β auto-discoverable workflows via `SKILL.md` (compatible with Claude Code's format).
+- π **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** β `/Library/Application Support/opencode/` (macOS), `/etc/opencode/` (Linux), `%ProgramData%\opencode` (Windows), plus macOS MDM preferences for enterprise rollouts.
-- π **AGENTS.md** is the canonical instructions file; `CLAUDE.md` is now a fallback only.
+- π **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.
-> π‘ For the source-of-truth list of releases, see the [OpenCode GitHub releases page](https://github.com/anomalyco/opencode/releases).
-
----
-
-### π Reading tips
-
-- **Reading on GitHub?** The in-page anchor links work natively. Use the table-of-contents button at the top of the file view for fast jumping.
-- **Want a richer markdown view?** This repo plays well with [Obsidian](https://obsidian.md/).
-- **On a phone?** Stick to the [Choose your path](#-choose-your-path) section at the top; the wider tables read best on desktop.
+> π‘ Source of truth: [GitHub releases](https://github.com/anomalyco/opencode/releases).
---
@@ -906,15 +695,14 @@ Set `bash` permission to `"ask"` at the project level (default for the `plan` ag
- [OpenCode docs (official)](https://opencode.ai/docs/)
- [OpenCode on GitHub](https://github.com/anomalyco/opencode)
-- [OpenCode Zen β model gateway](https://opencode.ai/docs/zen)
-- [Config schema reference](https://opencode.ai/config.json)
-- [TUI config schema](https://opencode.ai/tui.json)
-- [Official MCP registry](https://registry.modelcontextprotocol.io/)
-- [MCP protocol spec](https://modelcontextprotocol.io/)
-- [opencode.ai/download β desktop app](https://opencode.ai/download)
+- [OpenCode Zen](https://opencode.ai/docs/zen)
+- [Config schema](https://opencode.ai/config.json) Β· [TUI schema](https://opencode.ai/tui.json)
+- [Official MCP registry](https://registry.modelcontextprotocol.io/) Β· [Protocol spec](https://modelcontextprotocol.io/)
---
+**Reading tips:** Anchor links work natively on GitHub β tap the table-of-contents button at the top of the file view. On a phone, stick to [Choose your path](#-choose-your-path); wider tables read best on desktop.
+
> Features, pricing, and availability change frequently. Always check the [official OpenCode documentation](https://opencode.ai/docs/) for the most current information.
-*Last reviewed May 2026 Β· OpenCode v1.15.4 Β· Spotted something stale? [Open an issue](../../issues) or send a PR β see [`CONTRIBUTING.md`](CONTRIBUTING.md).*
+*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).*