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).*