From 7d347eef743523c47d2bd910f308c6ae09f533e2 Mon Sep 17 00:00:00 2001 From: Wesam Abousaid Date: Mon, 18 May 2026 19:59:14 +0200 Subject: [PATCH] docs: rewrite README and AGENTS.md with verified, balanced content README - Match the structure of common practical-guide repos: title, badges, install one-liner, "Choose your path", "When to use what" decision tree (mermaid) + table, "What's inside" topical map, deep dives, Limitations, FAQ, Updates, References. - Add explicit not-affiliated-with-OpenCode disclaimer per OpenCode's own README request for third-party projects using "opencode" in the name. - Add AI-coding caveat (you're still the reviewer, hallucinations are real) at the top. - Add balanced "When OpenCode isn't the right tool" subsection naming Claude Code, Cursor, Aider, Copilot, Codeium, Supermaven as better fits for specific use cases. - All factual claims verified against opencode.ai/docs and the JSON config schema. Pricing/model table dated 2026-05-18. AGENTS.md - Repurpose from generic React boilerplate to actually describe this repo: a documentation guide. Includes editing rules, style guide, emoji policy, and "when to update what" matrix. --- AGENTS.md | 235 ++++------ README.md | 1259 +++++++++++++++++++++++++++++++++++------------------ 2 files changed, 935 insertions(+), 559 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 80c1a84..5f383d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,172 +1,123 @@ -# OpenCode Agent Guidelines +# AGENTS.md -This document helps OpenCode understand your project's structure, conventions, and requirements. +> Project instructions for OpenCode. Read every session. -## Project Overview +## What this repo is -**Project Type**: [Describe your project type, e.g., React/TypeScript web application] -**Purpose**: [Brief description of what the project does] -**Key Technologies**: [List main technologies and frameworks] +A practical, opinionated guide to using [OpenCode](https://opencode.ai) — README, supporting docs, drop-in agent prompts, MCP walkthroughs, and a worked example of a fully-configured `.opencode/` directory. It's a **documentation repository**, not application code. -## Code Conventions +## Repo layout -### File Structure ``` -src/ -├── components/ # React components -├── pages/ # Page components -├── utils/ # Utility functions -├── hooks/ # Custom React hooks -├── types/ # TypeScript type definitions -└── styles/ # CSS/SCSS files +. +├── README.md # Main guide (the centerpiece) +├── AGENTS.md # This file +├── CONTRIBUTING.md # How to contribute +├── LICENSE # MIT +├── docs/ +│ ├── quickstart.md # 5-minute getting-started +│ ├── zen.md # Zen model gateway details +│ ├── tui.md # TUI mastery +│ ├── agents.md # Custom agent deep dive +│ ├── commands.md # Custom slash commands +│ ├── skills.md # Agent skills +│ ├── plugins.md # Plugin/hook system +│ ├── mcp.md # MCP integration +│ ├── workflows.md # Real-world recipes +│ ├── migration.md # Migration from Claude Code / Cursor +│ ├── faq.md # FAQ + troubleshooting +│ └── reference/ +│ ├── cli.md # All CLI commands +│ ├── slash-commands.md # All TUI slash commands +│ ├── permissions.md # Permission model +│ ├── changelog.md # OpenCode releases +│ └── further-reading.md # External resources +├── .opencode/ +│ ├── agents/ # Example custom agents +│ ├── commands/ # Example custom commands +│ └── skills/ # Example agent skills +├── mcp-servers/ # MCP server walkthroughs +├── specialized-agents/ # Drop-in specialist prompts +│ ├── system-prompts/ # System prompts (10 roles) +│ └── descriptions/ # Role descriptions +└── Images/ # Diagrams and screenshots ``` -### Naming Conventions -- **Files**: kebab-case (e.g., `user-profile.tsx`) -- **Components**: PascalCase (e.g., `UserProfile`) -- **Functions**: camelCase (e.g., `formatUserName`) -- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`) -- **Types**: PascalCase with `Type` suffix (e.g., `UserProfileType`) +## Editing rules -### Code Style -- **Indentation**: 2 spaces -- **Semicolons**: Yes -- **Quotes**: Single quotes for strings -- **Line length**: 100 characters max -- **Trailing commas**: Yes in objects and arrays +### Always -## Development Guidelines +- **Cite the source.** Every factual claim about OpenCode must trace back to [opencode.ai/docs](https://opencode.ai/docs/), the [GitHub repo](https://github.com/anomalyco/opencode), or an official release note. Don't paraphrase from memory. +- **Verify version-specific claims.** Pricing, model names, commands, and flags change. When in doubt, check the docs page that owns the topic. +- **Use OpenCode's actual terminology.** "Custom commands" not "slash skills"; "agents" and "subagents" not "personas"; "plugins" not "hooks" (OpenCode plugins serve the hook role). +- **Match the README's tone.** Practical, mental-model-first, prescriptive ("Reach for it when…"). No marketing fluff. +- **Update the `Last reviewed` date** at the bottom of the README when making material changes. -### Testing -- Write unit tests for all utility functions -- Use Jest and React Testing Library -- Test files should be next to source files (e.g., `component.tsx` and `component.test.tsx`) -- Aim for 80%+ test coverage +### Never -### Error Handling -- Use try/catch for async operations -- Log errors to console in development -- Show user-friendly error messages in production -- Validate all external inputs +- **Don't invent commands, flags, or features.** If you can't verify it, leave it out. +- **Don't hardcode prices without a "verified" date.** Always show the date next to any pricing table. +- **Don't add `Co-Authored-By` lines to commits** unless the user asks for them. +- **Don't `git push --force` to `main`**, ever, without explicit permission. +- **Don't introduce affiliate links or sponsorship blocks** without the maintainer's approval. -### Security -- Never commit secrets or API keys -- Validate and sanitize all user inputs -- Use environment variables for configuration -- Implement proper authentication and authorization +## Style conventions -### Performance -- Use React.memo() for expensive components -- Implement code splitting for large bundles -- Optimize images and assets -- Monitor bundle size +### Markdown -## Project-Specific Rules +- One blank line between sections. No trailing whitespace. +- Code fences with language tags: ` ```bash `, ` ```json `, ` ```markdown `. +- Internal links use anchor form: `[label](#section-id)`. Anchors are auto-derived from headings (lowercased, spaces → dashes, special chars stripped). +- Tables: header row, separator row, no leading/trailing pipes. Keep column widths reasonable for desktop reading. +- Callouts use blockquotes with emoji prefixes: + - `> 💡 **Pro Tip:** …` for tips + - `> ⚠️ **Warning:** …` for foot-guns + - `> 🆕 …` for new features + - `> 📚 …` for deeper-reading pointers +- Emoji policy: + - **OK** — one leading emoji on H2 navigation headings (🧭 🧠 📚 📖), and the callout-prefix set above. + - **Not OK** — decorative emoji inside prose, in code, or on H3/H4 headings. One per spot, never decorative density. -### Do's -- Use TypeScript strict mode -- Follow the existing component patterns -- Add comments for complex logic -- Update documentation when changing APIs -- Run tests before committing +### Code samples -### Don'ts -- Don't use `any` type in TypeScript -- Don't commit console.log statements -- Don't modify multiple concerns in one commit -- Don't ignore TypeScript/ESLint warnings -- Don't add dependencies without team approval +- **JSON examples** in this repo are valid `opencode.json` snippets — paste-ready. Include the `$schema` line on full-file examples. +- **Shell examples** assume a POSIX shell. Use `bash` fence; quote variables (`"$VAR"`). +- **Markdown front-matter** uses YAML with `---` fences. Match the exact key spelling from the OpenCode docs (e.g., `description`, `mode`, `model`, `permission`, `tools`). -## Common Patterns +### Tone -### API Calls -```typescript -// Use this pattern for API calls -async function fetchUser(id: string): Promise { - try { - const response = await api.get(`/users/${id}`); - return response.data; - } catch (error) { - console.error('Failed to fetch user:', error); - throw new Error('User not found'); - } -} -``` +- **Be concrete.** "Reach for it when X" beats "useful for X." +- **Lead with the mental model**, then the syntax, then the example. +- **Compare options side-by-side** when there's a choice to make (custom commands vs. skills, etc.). +- **Emoji discipline.** Allowed: H2 navigation marker, and the callout prefixes listed under "Markdown" above. Not allowed: decoration inside prose or on H3/H4 headings. -### Component Structure -```typescript -// Use this component structure -interface UserProfileProps { - userId: string; - onUpdate?: () => void; -} +## Commands -export function UserProfile({ userId, onUpdate }: UserProfileProps) { - const [user, setUser] = useState(null); - - useEffect(() => { - loadUser(); - }, [userId]); - - async function loadUser() { - const data = await fetchUser(userId); - setUser(data); - } - - if (!user) return ; - - return ( -
-

{user.name}

- {/* ... */} -
- ); -} -``` - -## Tool Configuration - -### Formatters -- **Prettier**: Use project prettier config -- **ESLint**: Follow Airbnb style guide with custom rules -- **TypeScript**: Strict mode enabled - -### Build Tools -- **Bundler**: Vite -- **Package Manager**: npm -- **CI/CD**: GitHub Actions - -## Getting Started - -1. **Install dependencies**: `npm install` -2. **Start development server**: `npm run dev` -3. **Run tests**: `npm test` -4. **Build for production**: `npm run build` -5. **Check code quality**: `npm run lint` - -## Helpful Commands +This repo has no build/test stack — it's pure markdown. Useful housekeeping: ```bash -# Format code -npm run format +# Spell-check (if installed) +codespell README.md docs/ -# Type check -npm run type-check - -# Run all checks -npm run check - -# Update dependencies -npm run update-deps +# Find broken internal links +grep -nE '\]\(#[a-z0-9-]+\)' README.md docs/*.md ``` -## Contact & Support +## How OpenCode should work in this repo -- **Team**: [Your team name] -- **Repository**: [GitHub repo URL] -- **Documentation**: [Docs URL] -- **Slack**: [Slack channel] +- **Default agent:** `build` is fine — edits are local-file-only and easily reversible. +- **No network-dependent tools needed** for editing docs. `webfetch`/`websearch` are useful only when verifying external claims. +- **Bash:** read-only commands (`ls`, `grep`, `git status`, `git diff`) are safe to auto-allow. Writes (`rm`, `mv`, `git push`) should always require confirmation. + +## When to update what + +| Trigger | What to update | +|---|---| +| New OpenCode release | `docs/reference/changelog.md` + version line in README footer | +| Pricing change | Pricing table in README + `docs/zen.md`, with new "verified" date | +| New built-in command | Slash-command list in README + `docs/reference/slash-commands.md` | +| Discovered factual error | Fix the source location; grep for repeats | --- -*This document is automatically generated and should be updated as the project evolves.* \ No newline at end of file +*This file is read by OpenCode at every session. Keep it short, accurate, and actionable.* diff --git a/README.md b/README.md index 0bd4af9..3f5d131 100644 --- a/README.md +++ b/README.md @@ -1,495 +1,920 @@ -# OpenCode: The Ultimate AI Coding Assistant +# OpenCode: Everything You Need to Know -> **The open-source, multi-provider AI coding tool that gives you freedom from vendor lock-in** +A practical guide to [OpenCode](https://opencode.ai) — from your first prompt to custom agents, skills, plugins, and MCP integrations. Built around clear mental models and real examples, not marketing. -[![OpenCode](https://raw.githubusercontent.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/main/Images/opencode.png)](https://opencode.ai) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE) +[![OpenCode v1.15.4](https://img.shields.io/badge/OpenCode-v1.15.4-7C3AED?style=flat-square)](https://github.com/anomalyco/opencode/releases) +[![Last reviewed](https://img.shields.io/badge/last%20reviewed-May%202026-22c55e?style=flat-square)](#updates--deprecations) +[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4?style=flat-square)](CONTRIBUTING.md) -## 🎯 Why OpenCode? - -If you're coming from **Claude Code**, **Cursor**, or **GitHub Copilot**, OpenCode offers something fundamentally different: - -| Feature | OpenCode (CLI ecosystem) | Claude Code | Cursor | GitHub Copilot | -| ----------------------- | -------------------------------------------------- | ------------------------------------ | ------------------------------------ | -------------------------------------------- | -| **Model Flexibility** | Multi-provider (OpenAI, Anthropic, DeepSeek, etc.) | Primarily Anthropic (Claude models) | Multi-provider (plan dependent) | Multi-provider (GitHub-managed) | -| **Pricing Model** | Pay-as-you-go (API usage based) | Subscription (e.g., Claude Pro tier) | Subscription (Pro tiers) | Subscription (Individual / Business tiers) | -| **Primary Interface** | Terminal-native (CLI-first) | Web app + integrations | Desktop editor (VS Code fork) | IDE extension (VS Code, JetBrains, etc.) | -| **Open Source** | open-source | Proprietary | Proprietary | Proprietary | -| **Customization** | High (config files, agents, workflows) | Moderate (prompt & tool configs) | High (rules, modes, project context) | Low–Moderate (custom instructions, policies) | -| **Target User** | Power users / terminal-heavy devs | Claude-centric users | Full IDE AI workflow users | Mainstream IDE users | - -### The OpenCode Advantage: -- **No vendor lock-in**: Use OpenAI, Anthropic, Google, local models, or all of them -- **Pay only for what you use**: No monthly subscriptions, transparent per-token pricing -- **Terminal-first workflow**: Stays in your development environment -- **Extensible architecture**: Create custom skills, agents, and workflows -- **Enterprise ready**: SSO, team workspaces, centralized configuration - ---- - -## 🚀 Quick Start (5 Minutes) - -### 1. Install OpenCode ```bash -# Recommended method curl -fsSL https://opencode.ai/install | bash - -# Alternative: Homebrew -brew install anomalyco/tap/opencode - -# Verify installation -opencode --version ``` -[![OpenCode Installation](https://raw.githubusercontent.com/wesammustafa/OpenCode-Everything-You-Need-to-Know/main/Images/opencode-installation.png)](https://opencode.ai/docs/#install) +**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). + +--- + +## 🧭 Choose your path + +| You are… | Start here | 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 | + +--- + +## 🧠 When to use what + +OpenCode has five extension points. Pick by trigger and surface: + +```mermaid +flowchart TD + Start([Repeatable task you want
OpenCode to do]) --> Q1{How does it trigger?} + Q1 -->|User types /name| Q2{Just a prompt template,
or a full role
with permissions?} + Q1 -->|Model auto-discovers
from a description| AS[Agent Skill
.opencode/skills/NAME/SKILL.md] + Q1 -->|Event in OpenCode
itself| Q3{Local code or
external system?} + Q2 -->|Prompt template| CC[Custom Command
.opencode/commands/NAME.md] + Q2 -->|Full role| CA[Custom Agent
.opencode/agents/NAME.md] + Q3 -->|Local JS/TS| PL[Plugin
.opencode/plugins/NAME.js] + 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` | + +> 💡 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 | -### 2. Set Up Zen (Recommended for Beginners) ```bash -# Start OpenCode +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 - -# In the TUI, run: -/connect - -# Select "opencode" and follow the link to get your API key -# Zen provides curated models with pay-as-you-go pricing ``` -### 3. Try Your First Commands +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 -# Start in your project directory -cd /path/to/your/project -opencode . - -# Ask OpenCode to analyze your code -What does this project do? @README.md - -# Get help with a specific file -Help me understand the authentication in @src/auth/ - -# Switch between Plan and Build modes (Tab key) -[Plan] How would you implement this feature? -[Build] Go ahead and implement it +# 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 ``` -### 4. Essential Keyboard Shortcuts -- **Tab**: Switch between Plan (read-only) and Build (read-write) modes -- **@**: Reference files in your project -- **!**: Execute shell commands -- **/**: Access slash commands -- **Ctrl+C**: Exit OpenCode +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. --- -## 📚 Core Concepts +### Configuring providers -OpenCode is built around four key pillars that work together: +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. -### 1. **Zen Model Router** - Your AI Model Gateway -Zen provides curated, optimized models specifically for coding with pay-as-you-go pricing. - -**Key Benefits:** -- Access to 75+ AI models with one API key -- Pay per token (no monthly subscriptions) -- Free models available for learning -- Team workspaces with centralized billing - -**Quick Setup:** -```bash -# Get your Zen API key -1. Visit: https://opencode.ai/auth -2. Sign up and add billing -3. Copy your API key -4. In OpenCode: /connect → select "opencode" - -# See available models -/models +```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}" + } + } + } +} ``` -**Popular Models & Pricing:** -| Model | Input | Output | Best For | -|-------|-------|--------|----------| -| GPT 5.2 Codex | $1.75/1M | $14/1M | General coding | -| Claude Sonnet 4.6 | $3-6/1M | $15-22.50/1M | Reasoning | -| Gemini 2.5 Pro | $2.50/1M | $10/1M | Multimodal | -| Qwen 2.5 Coder | $0.50/1M | $2/1M | Budget coding | -| MiniMax M2.5 Free | Free | Free | Learning | +**Variable substitution:** -> **💡 Pro Tip**: Start with free models to learn, then upgrade as needed. Most developers spend $5-20/month. +- `{env:NAME}` — pulls from the environment +- `{file:./path}` — reads from a local file (absolute or relative) -**[📖 Full Zen Guide](docs/ZEN-GUIDE.md)** | **[💰 Cost Calculator](https://opencode.ai/pricing)** +**Per-agent model override:** -### 2. **TUI Mastery** - Terminal-First Workflow -OpenCode's Terminal User Interface is where the magic happens. It's designed for developers who live in the terminal. - -**Essential Features:** -- **File References**: Use `@` to reference any file in your project -- **Shell Integration**: Execute commands with `!` prefix -- **Image Analysis**: Drag and drop images for UI/design references -- **Real-time Cost Display**: See token usage as you work - -**Workflow Example:** -```bash -# Reference files naturally -Can you fix the bug in @src/utils/validation.ts? - -# Use shell commands in context -!git status -Based on the changes, write commit messages - -# Analyze images -[Drag dashboard-mockup.png into terminal] -Create React components matching this design +```json +{ + "agent": { + "plan": { "model": "anthropic/claude-haiku-4-5" }, + "deep-thinker": { + "model": "openai/gpt-5", + "reasoningEffort": "high" + } + } +} ``` -**Productivity Tips:** -- Use `Tab` to switch between Plan (analysis) and Build (implementation) -- Chain commands: `!git diff | /analyze-changes` -- Search files: `@utils` finds utils directory or utils.ts files -- Multi-line input: `Shift+Enter` for complex queries - -**[🎮 Full TUI Guide](docs/TUI-MASTERY.md)** | **[⌨️ Keyboard Shortcuts](docs/TUI-MASTERY.md#essential-keyboard-shortcuts)** - -### 3. **AI Agents** - Specialized AI Personalities -Agents are specialized AI personas with specific tools, permissions, and behaviors. - -**Built-in Agents:** -- **Plan Agent** (Tab): Read-only analysis and planning -- **Build Agent** (Tab): Read-write implementation -- **Explore Subagent**: Codebase exploration -- **General Subagent**: Complex task execution - -**Create Custom Agents:** -```markdown -# ~/.config/opencode/agents/code-reviewer.md -name: Code Reviewer -model: claude-sonnet-4.6 -temperature: 0.2 - -## Instructions -You are a senior code reviewer. Focus on: -1. Security vulnerabilities -2. Performance bottlenecks -3. Code style consistency -4. Maintainability issues - -## Tools -- read: true -- ask: true -- write: false # Reviewer doesn't make changes -``` - -**Agent Workflow Patterns:** -```bash -# Plan → Build cycle -[Plan] How would you implement user authentication? -[Build] Implement the authentication system - -# Multi-agent collaboration -@explore Analyze security in @src/auth/ -@code-reviewer Review the proposed implementation -[Build] Implement with the suggested improvements -``` - -**[🤖 Full Agents Guide](docs/AGENTS-GUIDE.md)** | **[🎭 Agent Templates](.opencode/agents/)** - -### 4. **OpenCode Skills** - Workflow Automation -Skills are reusable behavior definitions that transform complex workflows into simple commands. - -**Example Skills:** -```bash -# Code review skill -/review @src/auth/ --focus security - -# Pull request creation -/pr "Add user authentication" - -# Test-driven development -/tdd "User registration with email validation" - -# Documentation generation -/docs api --output markdown -``` - -**Create Your Own Skill:** -```markdown -# .opencode/skills/deploy.md ---- -name: "Deploy" -description: "Automated deployment workflow" -tools: ["read", "write", "bash"] ---- - -# Deploy -1. Run tests: !npm test -2. Build project: !npm run build -3. Deploy to production: !deploy.sh -``` - -**[🔧 Full Skills Guide](docs/SKILLS-GUIDE.md)** | **[💼 Skill Examples](.opencode/skills/)** +> 📚 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. --- -## 🔄 Migration Guide for Experienced Developers +### Prompt Engineering Deep Dive -### Coming from Claude Code -**What's similar:** -- AI-assisted coding in your editor -- File context awareness -- Conversation history +> **📖 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. -**What's different:** -- **Model flexibility**: Multi-provider vs Claude-only -- **Pricing model**: Pay-as-you-go vs subscription -- **Primary interface**: Terminal-native vs desktop app -- **Customization depth**: High vs limited features +#### 1. Plan → Build cycle -**Migration steps:** -1. Install OpenCode and set up Zen -2. Try Claude models through Zen (often cheaper) -3. Learn TUI keyboard shortcuts (Tab is your friend) -4. Create custom agents for your workflow +OpenCode ships with two primary agents you can toggle between with **Tab**: -### Coming from Cursor -**What's similar:** -- AI-powered code generation -- Project context understanding -- Edit commands +| 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 | -**What's different:** -- **Philosophy**: Open-source vs proprietary -- **Integration**: Terminal vs IDE -- **Extensibility**: Skills system vs limited plugins -- **Pricing**: Transparent vs subscription +The natural workflow is **explore in plan, switch to build, commit**: -**Migration steps:** -1. Install OpenCode and connect providers -2. Practice file referencing with `@` syntax -3. Set up project-specific skills -4. Explore agent system for complex tasks - -### Coming from GitHub Copilot -**What's similar:** -- AI code completion -- Multi-language support -- IDE integration - -**What's different:** -- **Scope**: Full AI assistant vs autocomplete -- **Context**: Entire project vs current file -- **Interaction**: Conversational vs predictive -- **Pricing**: Usage-based vs subscription - -**Migration steps:** -1. Think of OpenCode as Copilot++ (full conversations) -2. Use for complex tasks beyond autocomplete -3. Leverage project-wide context -4. Create skills for repetitive tasks - -**[📋 Full Migration Guide](docs/MIGRATION-GUIDE.md)** - ---- - -## 🗺️ Learning Path - -### Week 1: Foundation -- [x] Install OpenCode and set up Zen -- [x] Learn basic TUI navigation (Tab, @, !, /) -- [x] Try free models for experimentation -- [ ] Complete the [Quick Start Guide](docs/QUICKSTART.md) - -### Week 2: Core Workflow -- [ ] Master file referencing and shell integration -- [ ] Practice Plan → Build cycle -- [ ] Set up your first custom agent -- [ ] Explore the [TUI Mastery Guide](docs/TUI-MASTERY.md) - -### Week 3: Advanced Features -- [ ] Create project-specific skills -- [ ] Set up team workspace (if applicable) -- [ ] Implement CI/CD integration -- [ ] Study the [Agents Guide](docs/AGENTS-GUIDE.md) - -### Week 4: Mastery -- [ ] Build custom MCP servers -- [ ] Create skill templates for your team -- [ ] Optimize model usage and costs -- [ ] Explore [Workflow Examples](docs/WORKFLOWS.md) - ---- - -## 📖 Detailed Documentation - -| Guide | Description | Time | -|-------|-------------|------| -| **[Quick Start](docs/QUICKSTART.md)** | Installation and first steps | 5 min | -| **[Zen Model Router](docs/ZEN-GUIDE.md)** | Model gateway and pricing | 15 min | -| **[TUI Mastery](docs/TUI-MASTERY.md)** | Terminal interface deep dive | 20 min | -| **[Agents Guide](docs/AGENTS-GUIDE.md)** | AI personas and workflows | 25 min | -| **[Skills Guide](docs/SKILLS-GUIDE.md)** | Workflow automation | 20 min | -| **[Commands Reference](docs/COMMANDS-REFERENCE.md)** | All slash commands | 10 min | -| **[MCP Guide](docs/MCP-GUIDE.md)** | Model Context Protocol | 30 min | -| **[Workflows](docs/WORKFLOWS.md)** | Real-world examples | 45 min | -| **[FAQ & Troubleshooting](docs/FAQ-TROUBLESHOOTING.md)** | Common issues and solutions | 10 min | - ---- - -## 🛠️ Command Reference - -### Essential Slash Commands -```bash -/help # Show all commands -/connect # Add/configure providers -/models # List available models -/agents # Manage AI agents -/skills # List available skills -/init # Initialize project analysis -/undo, /redo # Git-based undo/redo -/share # Create shareable conversation link -/export # Export to markdown +```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) ``` -### CLI Commands -```bash -# Start interactive TUI -opencode +> 💡 **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. -# Run single command -opencode run "Fix bug in @src/utils/validation.ts" +#### 2. Test-Driven Workflow -# Start HTTP server -opencode serve --port 3000 +Ideal for changes verifiable with unit or integration tests. -# Check usage stats -opencode stats +```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) ``` -**[📜 Full Command Reference](docs/COMMANDS-REFERENCE.md)** +Clear, executable targets (tests, mocks) drive iteration far more reliably than prose specs. ---- +#### 3. File references and shell -## 🔧 Project Configuration +Two characters that change how you talk to OpenCode: -### AGENTS.md Template -Each project can have an `AGENTS.md` file to guide 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 -# Project Guidelines -**Project Type**: React/TypeScript web app -**Purpose**: E-commerce platform -**Key Technologies**: React, TypeScript, Node.js, PostgreSQL +# AGENTS.md -## Code Conventions -- Files: kebab-case -- Components: PascalCase -- Functions: camelCase -- 2-space indentation -- Single quotes +## Commands +- build: `pnpm build` +- test: `pnpm test` +- lint: `pnpm lint && pnpm typecheck` -## Development Guidelines -- Write tests for all utilities -- Validate all external inputs -- Never commit secrets -- Use environment variables +## 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 ``` -**[📋 Sample AGENTS.md](AGENTS.md)** +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`: -### .opencode/ Directory Structure -``` -.opencode/ -├── agents/ -│ ├── code-reviewer.md -│ └── test-writer.md -├── skills/ -│ ├── review.md -│ └── pr.md -└── config.json +```json +{ + "instructions": ["CONTRIBUTING.md", "docs/style-guide.md", ".cursor/rules/*.md"] +} ``` +> 📚 Full guide: [opencode.ai/docs/rules](https://opencode.ai/docs/rules). + --- -## ❓ FAQ & Troubleshooting +### Slash Commands -### Common Issues +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 | +| `/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 | + +> 📚 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 slash commands — the 30-second version + +Save a prompt as a markdown file in `.opencode/commands/`, invoke it forever: -**Q: OpenCode command not found** ```bash -# Check installation -which opencode +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 -# Add to PATH -echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc -source ~/.bashrc +opencode # then type: /optimize ``` -**Q: Zen API key not working** -```bash -# Regenerate key at: https://opencode.ai/auth -# Then reconnect: -/connect -# Select "opencode" and paste new key -``` - -**Q: File references not working** -```bash -# Check current directory -!pwd - -# Use absolute path if needed -@/full/path/to/file.ts -``` - -**Q: High token usage** -```bash -# Switch to lighter model -/models -# Select Qwen 2.5 Coder or MiniMax Free - -# Use /compact to summarize long conversations -/compact -``` - -**Q: Images not displaying in OpenCode's TUI** -OpenCode's TUI is text-based and doesn't display images inline. Image links appear as markdown text. -- For local markdown preview tools (VS Code, Obsidian, etc.), use relative paths: `[![OpenCode](./Images/opencode.png)](https://opencode.ai)` -- If that doesn't work, try absolute path from repo root: `[![OpenCode](/Images/opencode.png)](https://opencode.ai)` -- For public repositories, use full GitHub URLs: `[![OpenCode](https://raw.githubusercontent.com/user/repo/main/Images/opencode.png)](https://opencode.ai)` - -**[❓ Full FAQ & Troubleshooting](docs/FAQ-TROUBLESHOOTING.md)** +→ Deep dive in [Custom Commands](#custom-commands). --- -## 🌐 Community & Resources +### Custom Commands -### Official Resources -- **Website**: [opencode.ai](https://opencode.ai) -- **Documentation**: [docs.opencode.ai](https://docs.opencode.ai) -- **GitHub**: [github.com/anomalyco/opencode](https://github.com/anomalyco/opencode) -- **Discord**: [Join Community](https://discord.gg/opencode) +> **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. + +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` in the TUI. + +| Frontmatter key | Purpose | +|---|---| +| `description` (required) | One-liner shown in the slash-command palette | +| `agent` | Which agent runs it (`build`, `plan`, or a custom one) | +| `model` | Override the model just for this command | +| `subtask` | `true` runs as a subagent (isolated context) | + +| Body placeholder | Substitutes | +|---|---| +| `$ARGUMENTS` / `$1` / `$2` | What the user typed after the command | +| `@` | File content (fuzzy resolved) | +| `` `!` `` | Shell stdout | + +**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). --- -## 📈 What's Next? +### Agent Skills -### Immediate Actions -1. **Install OpenCode** and try the free models -2. **Practice** the Plan → Build cycle (Tab key) -3. **Create** your first custom agent or skill -4. **Join** the community for support and inspiration +> **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. -### Long-term Goals -- **Master** all four pillars (Zen, TUI, Agents, Skills) -- **Build** a library of reusable skills for your workflow -- **Contribute** to the OpenCode ecosystem -- **Optimize** your AI-assisted development workflow +OpenCode uses Claude Code-compatible Agent Skill folders. Skill lookup paths (project → global → Claude-compatible → agent-compatible): + +``` +.opencode/skills//SKILL.md +~/.config/opencode/skills//SKILL.md +.claude/skills//SKILL.md +.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. + +**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). + +> 📚 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). --- -## 📄 License +### Plugins -OpenCode is open-source software licensed under the [MIT License](LICENSE). +> **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. -*Last updated: February 2026* -*For the best reading experience, install [Obsidian](https://obsidian.md/) to view these documents.* +#### Where plugins live -> **💡 Remember**: OpenCode is a tool to augment your skills, not replace them. The best developers use AI as a powerful assistant, not a crutch. \ No newline at end of file +| Scope | Path | +|---|---| +| Project | `.opencode/plugins/.{js,ts}` | +| Global | `~/.config/opencode/plugins/.{js,ts}` | +| NPM packages | `plugin` array in `opencode.json` | + +NPM-installed plugins: + +```json +{ + "plugin": [ + "opencode-helicone-session", + "opencode-wakatime", + "@my-org/custom-plugin" + ] +} +``` + +These auto-install via Bun and cache under `~/.cache/opencode/node_modules/`. + +Local plugins can use npm dependencies — drop a `package.json` next to them. + +#### 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/):** + +| File | What it does | +|---|---| +| [`protect-secrets.js`](.opencode/plugins/protect-secrets.js) | Blocks any tool call touching `.env*`, `secrets/`, SSH keys, etc. | +| [`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. + +> 📚 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). + +--- + +### Subagents + +> **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: `+↑/↓/←/→`). + +#### Built-in subagents + +| 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 | + +Invoke them by `@`-mentioning from your main session: + +```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 + +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 +mode: all +model: anthropic/claude-sonnet-4-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` → invoked as `@frontend-engineer` (subagent) or in the Tab cycle (primary). The mode determines surfaces: + +| `mode` | Where it appears | +|---|---| +| `primary` | Tab-cycle alongside `build`/`plan` | +| `subagent` | `@` mentions only | +| `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). + +--- + +### Model Context Protocol (MCP) + +> 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). + +```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 | logout | debug `. Reference a server's tools in a prompt with `use `. + +**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 — 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/). + +--- + +### 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. + +--- + +### 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. + +**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. + +**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. + +**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). + +**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). + +**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.15.4** *(May 17, 2026)*. Run `opencode upgrade` to get it. + +**Recent highlights (verified via [the OpenCode docs](https://opencode.ai/docs/)):** + +- 🆕 **Agent Skills compatibility** — auto-discoverable workflows via `SKILL.md` (compatible with Claude Code's format). +- 🆕 **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. + +> 💡 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. + +--- + +### 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 — 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) + +--- + +> 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).*