opencode-primer
Master OpenCode, the open-source AI coding agent — setup, agents, skills, plugins, MCP, Zen & headless CI.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/wesammustafa--opencode-primer)HTML
<a href="/listings/wesammustafa--opencode-primer"><img src="/api/listings/wesammustafa--opencode-primer/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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 — and as of July 2026 the [most-starred coding agent on GitHub](https://github.com/anomalyco/opencode) (182K+ stars), with [8M monthly users by the founder's count](https://betakit.com/qa-opencodes-founder-on-how-the-ai-agent-went-from-zero-to-8-million-users-in-a-year/).
**Three things it does that a chat UI can't:**
- **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 "<prompt>"` | Scripts, CI jobs, one-shot prompts | | **Server** | `opencode serve` or `opencode web` | Headless API, web UI, or remote attach |
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, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was [retired in June](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)
> ⚠️ **AI-coding caveat:** OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. **You're still the reviewer.** Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.
---
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.com/), [Windsurf (formerly Codeium)](https://windsurf.com/), or [Supermaven](https://supermaven.com/) — or alongside. | | **Quality depends on the underlying model** | OpenCode doesn't replace the LLM's reasoning. If your task fails on Sonnet, switching to OpenCode won't fix it. | | **Provider-agnostic ≠ provider-equivalent** | Some models tool-call better than others. A slug swap isn't free. | | **TUI on slow SSH / minimal terminals** | The TUI uses truecolor and complex layouts. Degrades over slow connections. `opencode serve` + `attach` or `opencode run` are better for those cases. | | **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 **Codex CLI**.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 732 lines · 2 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <img src="Images/banner.svg" alt="OpenCode Primer — everything you need to know about the open-source AI coding agent" width="100%">
- # OpenCode Primer
- Everything you need to know about [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Clear mental models, real examples, every fact verified against the current release.
- [](LICENSE)
- [](https://github.com/anomalyco/opencode/releases)
- [](#updates--deprecations)
- [](CONTRIBUTING.md)
- [](https://github.com/wesammustafa/opencode-primer/stargazers)
- ```bash
- curl -fsSL https://opencode.ai/install | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 14 on GitHub
- ```
- **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 canonical sources, check [opencode.ai/docs](https://opencode.ai/docs/) and [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode).
- > 💡 **Pro Tip:** If this guide saves you an afternoon, a ⭐ helps other developers find it.
- ---
- ## 🧭 Choose your path
- | You are… | Start with | Time |
- |---|---|---|
- | 🚀 **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 |
- <!-- Compatibility anchors for old internal links (auto-generated heading anchors
- handle: setup, opencode-zen, themes, agents, plugins, custom-commands,
- agent-skills, mcp-servers, prompt-engineering, tui--themes, headless--ci) -->
- <a id="opencode-setup"></a>
- <a id="configuring-providers"></a>
- <a id="prompt-engineering-deep-dive"></a>
- <a id="tui-mastery"></a>
- <a id="subagents"></a>
- <a id="custom-agents"></a>
- <a id="model-context-protocol-mcp"></a>
- <a id="when-to-use-what"></a>
- <a id="whats-inside"></a>
- ---
- ## Getting started
- ### 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 — and as of July 2026 the [most-starred coding agent on GitHub](https://github.com/anomalyco/opencode) (182K+ stars), with [8M monthly users by the founder's count](https://betakit.com/qa-opencodes-founder-on-how-the-ai-agent-went-from-zero-to-8-million-users-in-a-year/).
- **Three things it does that a chat UI can't:**
- - **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 "<prompt>"` | 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, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was [retired in June](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)
- > ⚠️ **AI-coding caveat:** OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. **You're still the reviewer.** Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.
- ---
- ### 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.com/), [Windsurf (formerly Codeium)](https://windsurf.com/), or [Supermaven](https://supermaven.com/) — or alongside. |
- | **Quality depends on the underlying model** | OpenCode doesn't replace the LLM's reasoning. If your task fails on Sonnet, switching to OpenCode won't fix it. |
- | **Provider-agnostic ≠ provider-equivalent** | Some models tool-call better than others. A slug swap isn't free. |
- | **TUI on slow SSH / minimal terminals** | The TUI uses truecolor and complex layouts. Degrades over slow connections. `opencode serve` + `attach` or `opencode run` are better for those cases. |
- | **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 **Codex CLI**.
- - Deeply embedded in VS Code workflow → **Cursor** or **GitHub Copilot**.
- - Want a small Python tool you can read end-to-end → **[Aider](https://aider.chat/)** (note: development has slowed markedly in 2026).
- - Don't want to manage provider keys → a managed hosted product, or [OpenCode Go](#opencode-go).
- > OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.
- ---
- ### Setup
- > ⏱️ **5 minutes** from zero to first AI-assisted commit.
- #### 1. Install
- ```bash
- curl -fsSL https://opencode.ai/install | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 111 on GitHub
- ```
- 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 github:anomalyco/opencode # mise users
- docker run -it --rm ghcr.io/anomalyco/opencode # Docker
- ```
- A desktop app for macOS / Windows / Linux is in beta at [opencode.ai/download](https://opencode.ai/download).
- #### 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**. Four ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:
- | | Best for | Trade-off |
- |---|---|---|
- | **Direct providers** (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure) | You already have credits with a provider | Manage one key per provider |
- | **[OpenCode Zen](#opencode-zen)** — pay-as-you-go gateway | One key, curated lineup, no commitment | Pricier per token than going direct in some cases |
- | **[OpenCode Go](#opencode-go)** — flat-rate subscription | Predictable $10/month, zero key management | Curated open models only, usage limits |
- | **Local models** (Ollama, LM Studio, llama.cpp) | Offline, strict data-residency, hobbyist | Quality varies hugely with model and hardware |
- There's no universally right answer — pick what fits.
- > ⚠️ **Warning:** You can no longer sign in with a Claude Pro/Max subscription. OpenCode removed its built-in Anthropic OAuth login in March 2026 at Anthropic's legal request ([PR #18186](https://github.com/anomalyco/opencode/pull/18186)). Anthropic models still work fine — via an **API key** in the provider config below, or via **Zen**.
- #### Direct provider config
- ```json
- {
- "$schema": "https://opencode.ai/config.json",
- "model": "anthropic/claude-sonnet-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.5", "options": { "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/<model-id>` 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-07-05; check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for current)*
- | Model ID | Input / Output (per MTok) | Reach for it when… |
- |---|---|---|
- | `opencode/claude-fable-5` | $10 / $50 | Absolute frontier — the hardest reasoning problems |
- | `opencode/claude-opus-4-8` | $5 / $25 | Flagship reasoning — complex refactors, large multi-file work |
- | `opencode/claude-sonnet-5` | $2 / $10 | Balanced everyday coding — newer *and* cheaper than Sonnet 4.6 |
- | `opencode/claude-haiku-4-5` | $1 / $5 | Fast, lightweight tasks |
- | `opencode/gpt-5.5` *(≤272K)* | $5 / $30 | Long-context, OpenAI ecosystem |
- | `opencode/gpt-5.4-mini` | $0.75 / $4.50 | Cost-efficient frontier |
- | `opencode/gemini-3.1-pro` *(≤200K)* | $2 / $12 | Multimodal, Google ecosystem |
- | `opencode/qwen3.7-plus` | $0.40 / $1.60 | Budget-friendly heavy lifting |
- **Free tier** *(rotating, time-limited, for community feedback):* `big-pickle` *(stealth)*, `deepseek-v4-flash-free`, `mimo-v2.5-free`, `north-mini-code-free`, `nemotron-3-ultra-free`.
- > 📚 Full lineup, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, DeepSeek, Grok, and the Claude Opus 4.8/4.7/4.6/4.5 line: [opencode.ai/docs/zen](https://opencode.ai/docs/zen) · Deeper guide (incl. deprecation sunset dates): [`docs/zen.md`](docs/zen.md).
- > 💡 **Pattern: cheap explorer / strong executor.** Use a cheap model (`qwen3.7-plus`, `gpt-5.4-mini`) for `explore` and `scout` subagents that read a lot, and a stronger one (`claude-sonnet-5` or `claude-opus-4-8`) for the main `build` agent that does the editing.
- #### OpenCode Go
- The flat-rate alternative to Zen: **$10/month ($5 your first month)** for a curated set of hosted open coding models — no API keys, no per-token math. Usage limits apply (roughly $12 per 5 hours / $30 per week / $60 per month of equivalent usage); past them, Go can fall back to a Zen balance.
- **Zen vs. Go in one line:** Zen bills per token across the full lineup; Go is a fixed subscription to open models. Reach for Go to learn and hack on a predictable budget; reach for Zen (or direct keys) when you want frontier models. Details: [opencode.ai/docs/go](https://opencode.ai/docs/go/) · [`docs/zen.md`](docs/zen.md).
- ---
- ## 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] > <Tab>
- [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://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/overview).
- #### File references and shell
- | Syntax | Effect | Example |
- |---|---|---|
- | `@<path>` | Attach file content (fuzzy resolved) | `look at @src/api/auth.ts` |
- | `!<cmd>` | 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/<name>.json` (project) or `~/.config/opencode/themes/<name>.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 <id>` (resume), `--fork` (branch a session), `--share` (publish), `--format json` (machine-readable), `--file <path>` (attach), `--replay` (interactive replay, v1.16+), `--auto` (auto-approve everything not `deny` — **CI only**). There's also a lightweight `--mini` mode (v1.17.10+).
- Sessions, stats, sharing:
- ```bash
- opencode session list # past sessions
- opencode stats --days 30 --models # token & cost by model
- opencode export <id> --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/<id>`). 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
- Start([Repeatable task you want<br/>OpenCode to do]) --> Q1{How does it trigger?}
- Q1 -->|User types /name| Q2{Just a prompt template,<br/>or a full role<br/>with permissions?}
- Q1 -->|Model auto-discovers<br/>from a description| AS[Agent Skill<br/>.opencode/skills/NAME/SKILL.md]
- Q1 -->|Event in OpenCode<br/>itself| Q3{Local code or<br/>external system?}
- Q2 -->|Prompt template| CC[Custom Command<br/>.opencode/commands/NAME.md]
- Q2 -->|Full role| CA[Custom Agent<br/>.opencode/agents/NAME.md]
- Q3 -->|Local JS/TS| PL[Plugin<br/>.opencode/plugins/NAME.js]
- Q3 -->|External tool| MCP[MCP Server<br/>opencode.json → mcp]
- ```
- | Extension | Triggered by | Lives in |
- |---|---|---|
- | [Custom Commands](#custom-commands) | User typing `/<name>` | `.opencode/commands/*.md` |
- | [Agent Skills](#agent-skills) | Model auto-discovery (description match) | `.opencode/skills/<name>/SKILL.md` |
- | [Plugins](#plugins) | Lifecycle events (tool calls, file edits, sessions) | `.opencode/plugins/*.{js,ts}` |
- | [Agents](#agents) | Tab key or `@<name>` mention | `.opencode/agents/<name>.md` |
- | [MCP Servers](#mcp-servers) | Prompt-driven external tool use | `opencode.json` → `mcp` |
- > 💡 These five compose. Most polished workflows combine 2–3.
- ---
- ### Slash Commands
- OpenCode ships a set of built-in slash commands plus everything you write yourself.
- | Command | What it does |
- |---|---|
- | `/init` | Guided generation of `AGENTS.md` |
- | `/help` | Show the help dialog |
- | `/new` *(`/clear`)* | New session |
- | `/sessions` *(`/resume`, `/continue`)* | List and switch sessions |
- | `/models` | Browse models |
- | `/connect` | Add a provider |
- | `/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 |
- Custom commands can override built-ins with the same name.
- > 📚 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. Save as `.opencode/commands/<name>.md`, invoke as `/<name>` in the TUI — with `$ARGUMENTS`, `@file`, and `!shell` interpolated at invocation time.
- Minimal example:
- ```markdown
- ---
- description: Run tests and triage failures
- agent: build
- ---
- !`pnpm test --reporter=verbose`
- 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`.
- | Frontmatter key | Purpose |
- |---|---|
- | `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 child session) |
- | Body placeholder | Substitutes |
- |---|---|
- | `$ARGUMENTS` / `$1` / `$2` | Text after the command name |
- | `@<path>` | File content (fuzzy resolved) |
- | ``!`<cmd>` `` | Shell stdout (backticks required in templates) |
- This repo ships four examples in [`.opencode/commands/`](.opencode/commands/): `/review`, `/pr`, `/test`, `/optimize`.
- > 📚 Deep dive: [`docs/commands.md`](docs/commands.md) · [opencode.ai/docs/commands](https://opencode.ai/docs/commands).
- ---
- ### Agent Skills
- > **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. Lookup paths (project → global → Claude-compat → Agent-compat):
- ```
- .opencode/skills/<name>/SKILL.md
- ~/.config/opencode/skills/<name>/SKILL.md
- .claude/skills/<name>/SKILL.md
- .agents/skills/<name>/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.
- **Command vs. skill, in one line:** commands are user-invoked (`/<name>`), 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).
- > 📚 Deep dive: [`docs/skills.md`](docs/skills.md) · [opencode.ai/docs/skills](https://opencode.ai/docs/skills).
- ---
- ### Plugins
- > **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.
- Two locations:
- ```
- .opencode/plugins/<name>.{js,ts} # project
- ~/.config/opencode/plugins/<name>.{js,ts} # global
- ```
- Plus npm packages via the `plugin` array in `opencode.json`:
- ```json
- { "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"] }
- ```
- Auto-installed via Bun, cached under `~/.cache/opencode/node_modules/`.
- 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/):
- | File | What it does |
- |---|---|
- | [`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.
- > 📚 Deep dive: [`docs/plugins.md`](docs/plugins.md) · [opencode.ai/docs/plugins](https://opencode.ai/docs/plugins).
- ---
- ### Agents
- OpenCode ships five built-in agents, and you can define your own as markdown files.
- #### Built-in
- | 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 |
- `Tab` cycles primaries. `@<name>` invokes a subagent.
- #### Custom
- Drop a markdown file in `.opencode/agents/`:
- ```markdown
- ---
- description: Senior frontend engineer — Tailwind + React + TypeScript
- mode: all
- model: anthropic/claude-sonnet-5
- permission:
- edit: allow
- bash:
- "*": "ask"
- "pnpm test*": "allow"
- "git status*": "allow"
- ---
- You're a senior frontend engineer working on a React/Tailwind codebase…
- ```
- 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` | `@<name>` mentions only (runs in a child session) |
- | `all` | Both |
- 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 15 permission keys, JSON-form alternative: [`docs/agents.md`](docs/agents.md) · [`docs/reference/permissions.md`](docs/reference/permissions.md).
- ---
- ### 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 with automatic OAuth via Dynamic Client Registration (RFC 7591).
- ```json
- {
- "$schema": "https://opencode.ai/config.json",
- "mcp": {
- "playwright": {
- "type": "local",
- "command": ["npx", "-y", "@playwright/mcp@latest"]
- },
- "context7": {
- "type": "remote",
- "url": "https://mcp.context7.com/mcp",
- "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
- },
- "sentry": {
- "type": "remote",
- "url": "https://mcp.sentry.dev/mcp",
- "oauth": {}
- }
- }
- }
- ```
- Manage from the CLI: `opencode mcp add | list | auth <name> | logout <name> | debug <name>`. Reference a server's tools in a prompt with `use <server-name>`.
- Featured walkthroughs in [`mcp-servers/`](./mcp-servers/):
- | Server | What it adds |
- |---|---|
- | [Playwright](./mcp-servers/playwright.md) | Browser automation — DOM, network, screenshots, accessibility |
- | [Context7](./mcp-servers/context7.md) | Live, version-pinned library docs piped into the prompt |
- | [Sentry](./mcp-servers/sentry.md) | Errors, traces, releases |
- | [Grep by Vercel](./mcp-servers/grep.md) | Code search across GitHub |
- > ⚠️ **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: [`docs/mcp.md`](docs/mcp.md) · [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers) · [Registry](https://registry.modelcontextprotocol.io/).
- ---
- ## 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 per token; [OpenCode Go](#opencode-go) is a flat $10/month for hosted open models; BYOK works for direct providers.
- **Does OpenCode work without an internet connection?**
- Yes, with a local model (Ollama, LM Studio, llama.cpp). Network is needed for hosted providers, remote MCP servers, sharing, and updates.
- **Can I migrate from Claude Code?**
- 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. Commands are **explicit** (user types `/<name>`); 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, 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.
- ---
- ### Updates & Deprecations
- *[→ Full changelog in `docs/reference/changelog.md`](docs/reference/changelog.md)*
- **Current release:** **v1.17.13** *(2026-07-01)*. Run `opencode upgrade` to get it.
- **New in v1.17:**
- - 🆕 **Session snapshots & revert** *(v1.17.11)* — roll a session back to an earlier message, including the file changes it made.
- - 🆕 **TUI yolo mode** *(v1.17.12)* — auto-approve permission prompts from inside the TUI; plus adaptive thinking for Claude Sonnet 5.
- - 🆕 **MCP resources** *(v1.17.10)* — resource template listing and resource-read tools, and MCP server instructions now land in session context. Local servers also gained a `cwd` option *(v1.17.4)*.
- - 🆕 **`--mini` CLI mode & V2 plugin API** *(v1.17.10)* — a lightweight CLI surface, namespaced plugin hooks, and Effect/Promise plugin support.
- - ⚡ **Faster file search** (new `fff`-backed tools), WSL-backed desktop on Windows, and a desktop v2 refresh (Chrome-style tabs, searchable model picker) *(v1.17.0–v1.17.13)*.
- - ⚠️ **Deprecation:** the `reference` config key is now `references` *(v1.17.1; old entries still load)*.
- **Still recent (v1.16):**
- - **File-based agents & skill discovery** — drop-in agent markdown files and `SKILL.md` discovery are GA; scaffold an agent with `opencode agent create`.
- - **Workspace cloning & session mobility** — managed workspace clones keep dirty/untracked files; move sessions between workspaces and directories.
- - **`opencode run --replay`** — interactively replay a run as it streams.
- - **~38% faster startup**, OpenAI models via AWS Bedrock, GitHub Copilot usage tracking.
- - 📝 **AGENTS.md** is canonical; `CLAUDE.md` is a fallback only.
- > 💡 Source of truth: [GitHub releases](https://github.com/anomalyco/opencode/releases).
- ---
- ### References
- *[→ Full reading list in `docs/reference/further-reading.md`](docs/reference/further-reading.md)*
- **Most-clicked starting points:**
- - [OpenCode docs (official)](https://opencode.ai/docs/)
- - [OpenCode on GitHub](https://github.com/anomalyco/opencode)
- - [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 2026-07-05 · OpenCode v1.17.13 · Spotted something stale? [Open an issue](https://github.com/wesammustafa/opencode-primer/issues) or send a PR — see [`CONTRIBUTING.md`](CONTRIBUTING.md).*
- **Found this useful? [Give it a ⭐](https://github.com/wesammustafa/opencode-primer) — it's how other developers discover the guide.**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.