OpenCode Primer

Everything you need to know about OpenCode — from your first prompt to custom agents, skills, plugins, and MCP integrations. Clear mental models, real examples, every fact verified against the current release.

curl -fsSL https://opencode.ai/install | bash

Who this is for: Developers using (or about to use) OpenCode. Beginners get a guided path; power users get depth on Custom Commands, Skills, Plugins, MCP, and Agents.

⚖️ Not affiliated with the OpenCode team. This is a community-maintained guide. For canonical sources, check opencode.ai/docs and github.com/anomalyco/opencode.

💡 Pro Tip: If this guide saves you an afternoon, a ⭐ helps other developers find it.

🧭 Choose your path

You are…	Start with	Time
🚀 New to OpenCode	What is it → Setup → Prompt Engineering	~15 min
⚡ Already using it	Custom Commands · Skills · Plugins · MCP	~20 min each
🧠 Configuring or headless	Agents · Headless & CI · Models & Providers	varies

Getting started

What is OpenCode?

OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by Anomaly, MIT-licensed — and as of July 2026 the most-starred coding agent on GitHub (182K+ stars), with 8M monthly users by the founder's count.

Three things it does that a chat UI can't:

Reads your actual repo — not pasted snippets. Greps your files, follows imports, grounds answers in real context using built-in read/grep/glob tools.
Edits in place and runs your stack — diff-aware edit/write/apply_patch, then bash to run your tests, linter, or build on the spot.
Composes with the rest of your toolchain — multi-provider models, custom slash commands, agent skills, JS/TS plugins, MCP servers, LSP, formatters, and an HTTP server for CI use.

Three interfaces:

Surface	Command	When
TUI (default)	`opencode`	Interactive day-to-day work in your terminal
CLI / headless	`opencode run "<prompt>"`	Scripts, CI jobs, one-shot prompts
Server	`opencode serve` or `opencode web`	Headless API, web UI, or remote attach

opencode                                       # start TUI in the current repo
opencode run "fix the failing test in src/api.test.ts"
opencode serve --port 4096                     # headless server

OpenCode sits in the same space as Claude Code, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was retired in June in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)

⚠️ AI-coding caveat: OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. You're still the reviewer. Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.

When OpenCode isn't the right tool

Limitation	Detail
No inline editor completion	OpenCode is a conversational agent, not Copilot-style autocomplete. For ghost-text-while-you-type, reach for Copilot, Cursor Tab, Windsurf (formerly Codeium), or Supermaven — 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 call them "available for a limited time." Don't build production on them.
Docs lag shipping	OpenCode moves fast. This guide and even the official docs occasionally trail the actual binary.
Not a substitute for code review	Diff-aware edits + passing tests don't guarantee correct, secure, or maintainable code. Treat AI output as a junior teammate's PR.

When something else fits better:

Want a polished single-vendor product → Claude Code or Codex CLI.
Deeply embedded in VS Code workflow → Cursor or GitHub Copilot.
Want a small Python tool you can read end-to-end → Aider (note: development has slowed markedly in 2026).
Don't want to manage provider keys → a managed hosted product, or OpenCode Go.

OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.

Setup

⏱️ 5 minutes from zero to first AI-assisted commit.

1. Install

curl -fsSL https://opencode.ai/install | bash

Other supported installers (pick whichever you already use):

npm i -g opencode-ai@latest         # npm / pnpm / yarn / bun all work
brew install anomalyco/tap/opencode # macOS / Linux
scoop install opencode              # Windows
choco install opencode              # Windows
sudo pacman -S opencode             # Arch
paru -S opencode-bin                # Arch (AUR)
mise use -g github:anomalyco/opencode      # mise users
docker run -it --rm ghcr.io/anomalyco/opencode  # Docker

A desktop app for macOS / Windows / Linux is in beta at opencode.ai/download.

2. Authenticate

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

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.

📝 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/ directory is a working example:

Path	What it does
`.opencode/agents/`	Custom agent definitions (markdown + YAML)
`.opencode/commands/`	Custom slash commands
`.opencode/plugins/`	Working JS plugins (audit log, secret blocker)
`.opencode/skills/`	Agent skills with `SKILL.md` files
`AGENTS.md`	Project instructions OpenCode reads every session
`opencode.json`	Project config with safe defaults

Models & Providers

OpenCode is provider-agnostic. Four ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture:

	Best for	Trade-off
Direct providers (Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure)	You already have credits with a provider	Manage one key per provider
OpenCode Zen — pay-as-you-go gateway	One key, curated lineup, no commitment	Pricier per token than going direct in some cases
OpenCode Go — flat-rate subscription	Predictable $10/month, zero key management	Curated open models only, usage limits
Local models (Ollama, LM Studio, llama.cpp)	Offline, strict data-residency, hobbyist	Quality varies hugely with model and hardware

There's no universally right answer — pick what fits.

⚠️ Warning: You can no longer sign in with a Claude Pro/Max subscription. OpenCode removed its built-in Anthropic OAuth login in March 2026 at Anthropic's legal request (PR #18186). Anthropic models still work fine — via an API key in the provider config below, or via Zen.

Direct provider config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5",
  "provider": {
    "anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } },
    "openai":    { "options": { "apiKey": "{file:~/.secrets/openai-key}" } }
  }
}

Variable substitution: {env:NAME} (environment) or {file:./path} (file content, absolute or relative).

Per-agent model override:

{
  "agent": {
    "plan":         { "model": "anthropic/claude-haiku-4-5" },
    "deep-thinker": { "model": "openai/gpt-5.5", "options": { "reasoningEffort": "high" } }
  }
}

OpenCode Zen

A curated, pay-as-you-go AI gateway. The OpenCode team tests and tunes models for coding-agent workloads; you get one key and a benchmarked lineup. Reference Zen models with the opencode/<model-id> namespace.

# 1. Sign up at https://opencode.ai/auth, add billing, copy API key
# 2. In OpenCode:
/connect            # pick "OpenCode Zen", paste key
/models             # browse the lineup

Pricing snapshot (verified 2026-07-05; check opencode.ai/docs/zen for current)

Model ID	Input / Output (per MTok)	Reach for it when…
`opencode/claude-fable-5`	$10 / $50	Absolute frontier — the hardest reasoning problems
`opencode/claude-opus-4-8`	$5 / $25	Flagship reasoning — complex refactors, large multi-file work
`opencode/claude-sonnet-5`	$2 / $10	Balanced everyday coding — newer and cheaper than Sonnet 4.6
`opencode/claude-haiku-4-5`	$1 / $5	Fast, lightweight tasks
`opencode/gpt-5.5` (≤272K)	$5 / $30	Long-context, OpenAI ecosystem
`opencode/gpt-5.4-mini`	$0.75 / $4.50	Cost-efficient frontier
`opencode/gemini-3.1-pro` (≤200K)	$2 / $12	Multimodal, Google ecosystem
`opencode/qwen3.7-plus`	$0.40 / $1.60	Budget-friendly heavy lifting

Free tier (rotating, time-limited, for community feedback): big-pickle (stealth), deepseek-v4-flash-free, mimo-v2.5-free, north-mini-code-free, nemotron-3-ultra-free.

📚 Full lineup, cached-read/write rates, GPT-5 Codex variants, Gemini, GLM, Kimi, MiniMax, DeepSeek, Grok, and the Claude Opus 4.8/4.7/4.6/4.5 line: opencode.ai/docs/zen · Deeper guide (incl. deprecation sunset dates): docs/zen.md.

💡 Pattern: cheap explorer / strong executor. Use a cheap model (qwen3.7-plus, gpt-5.4-mini) for explore and scout subagents that read a lot, and a stronger one (claude-sonnet-5 or claude-opus-4-8) for the main build agent that does the editing.

OpenCode Go

The flat-rate alternative to Zen: $10/month ($5 your first month) for a curated set of hosted open coding models — no API keys, no per-token math. Usage limits apply (roughly $12 per 5 hours / $30 per week / $60 per month of equivalent usage); past them, Go can fall back to a Zen balance.

Zen vs. Go in one line: Zen bills per token across the full lineup; Go is a fixed subscription to open models. Reach for Go to learn and hack on a predictable budget; reach for Zen (or direct keys) when you want frontier models. Details: opencode.ai/docs/go · docs/zen.md.

Using OpenCode

Prompt Engineering

📖 Project Initialization. Run /init to auto-generate an AGENTS.md. Treat it like any frequently-used prompt — iterate on it. Don't just dump 500 lines and forget.

Plan → Build cycle

Two primary agents you toggle with Tab:

Agent	What changes	Use it for
`plan`	`edit` and `bash` default to `ask` — analysis without surprise writes	Reading code, designing approaches, reviewing diffs
`build`	Full tool access (default)	Implementation, refactors, running tests

Natural workflow:

[plan]  > how would you implement OAuth for this app?
       (reads, plans, proposes — no writes)
[plan]  > <Tab>
[build] > do it
       (implements, edits, runs tests)

💡 Prompts like think hard, think more, or ultrathink nudge reasoning depth on supported models — the same pattern in the Anthropic prompt engineering guide.

File references and shell

Syntax	Effect	Example
`@<path>`	Attach file content (fuzzy resolved)	`look at @src/api/auth.ts`
`!<cmd>`	Run shell, inject output	`!git diff` then ask about it

> 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

# 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.

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "leader_timeout": 2000,
  "keybinds": { "command_list": "ctrl+p" }
}

Custom themes: .opencode/themes/<name>.json (project) or ~/.config/opencode/themes/<name>.json (global). Truecolor terminals required.

📚 Deep dive: docs/tui.md · opencode.ai/docs/keybinds · opencode.ai/docs/themes.

Headless & CI

Three ways to run OpenCode unattended:

# 1. One-shot prompts
opencode run "summarize the last 5 commits"
opencode run --format json "list every TODO with file and line" > todos.json
opencode run --agent plan --model anthropic/claude-haiku-4-5 \
  "audit src/ for missing input validation"

# 2. Headless server / web UI
opencode serve --port 4096 --hostname 0.0.0.0
opencode web   --port 4096

# 3. GitHub agent
opencode github install     # add a workflow file to your repo
opencode pr 123             # check out PR #123 and start a session

Useful run flags: --continue / --session <id> (resume), --fork (branch a session), --share (publish), --format json (machine-readable), --file <path> (attach), --replay (interactive replay, v1.16+), --auto (auto-approve everything not deny — CI only). There's also a lightweight --mini mode (v1.17.10+).

Sessions, stats, sharing:

opencode session list                  # past sessions
opencode stats --days 30 --models      # token & cost by model
opencode export <id> --sanitize        # JSON dump (with redaction)
opencode import session.json           # restore from JSON or share URL

📚 Full CLI reference: docs/reference/cli.md. CI recipes (GitHub Actions, GitLab CI): docs/workflows.md.

Sharing

/share generates a public link to the current session (opncd.ai/s/<id>). Three modes via opencode.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:

flowchart TD
    Start([Repeatable task you want<br/>OpenCode to do]) --> Q1{How does it trigger?}
    Q1 -->|User types /name| Q2{Just a prompt template,<br/>or a full role<br/>with permissions?}
    Q1 -->|Model auto-discovers<br/>from a description| AS[Agent Skill<br/>.opencode/skills/NAME/SKILL.md]
    Q1 -->|Event in OpenCode<br/>itself| Q3{Local code or<br/>external system?}
    Q2 -->|Prompt template| CC[Custom Command<br/>.opencode/commands/NAME.md]
    Q2 -->|Full role| CA[Custom Agent<br/>.opencode/agents/NAME.md]
    Q3 -->|Local JS/TS| PL[Plugin<br/>.opencode/plugins/NAME.js]
    Q3 -->|External tool| MCP[MCP Server<br/>opencode.json → mcp]

Extension	Triggered by	Lives in
Custom Commands	User typing `/<name>`	`.opencode/commands/*.md`
Agent Skills	Model auto-discovery (description match)	`.opencode/skills/<name>/SKILL.md`
Plugins	Lifecycle events (tool calls, file edits, sessions)	`.opencode/plugins/*.{js,ts}`
Agents	Tab key or `@<name>` mention	`.opencode/agents/<name>.md`
MCP Servers	Prompt-driven external tool use	`opencode.json` → `mcp`

💡 These five compose. Most polished workflows combine 2–3.

Slash Commands

OpenCode ships a set of built-in slash commands plus everything you write yourself.

Command	What it does
`/init`	Guided generation of `AGENTS.md`
`/help`	Show the help dialog
`/new` (`/clear`)	New session
`/sessions` (`/resume`, `/continue`)	List and switch sessions
`/models`	Browse models
`/connect`	Add a provider
`/themes`	Switch theme
`/compact` (`/summarize`)	Compact session to save tokens
`/share` · `/unshare`	Public link control
`/export`	Export to markdown
`/undo` · `/redo`	Walk edit history
`/editor`	Open `$EDITOR`
`/details` · `/thinking`	Toggle visibility of tool / reasoning blocks
`/exit` (`/quit`, `/q`)	Exit

Custom commands can override built-ins with the same name.

📚 Full reference: docs/reference/slash-commands.md.

Custom Commands

Mental model: A custom command is a prompt template you've named. Save as .opencode/commands/<name>.md, invoke as /<name> in the TUI — with $ARGUMENTS, @file, and !shell interpolated at invocation time.

Minimal example:

---
description: Run tests and triage failures
agent: build
---

!`pnpm test --reporter=verbose`

If any tests failed above, open the failing files and propose precise fixes.
Otherwise, summarize the coverage.

Save as .opencode/commands/test.md → invoke with /test.

Frontmatter key	Purpose
`description` (required)	Shown in the slash-command palette
`agent`	Which agent runs it (`build`, `plan`, or custom)
`model`	Override the model just for this command
`subtask`	`true` runs as a subagent (isolated child session)

Body placeholder	Substitutes
`$ARGUMENTS` / `$1` / `$2`	Text after the command name
`@<path>`	File content (fuzzy resolved)
!`<cmd>`	Shell stdout (backticks required in templates)

This repo ships four examples in .opencode/commands/: /review, /pr, /test, /optimize.

📚 Deep dive: docs/commands.md · opencode.ai/docs/commands.

Agent Skills

Mental model: A skill is a discoverable workflow. The agent sees the skill's name and description and decides on its own to load it when the task matches. You don't have to remember to invoke — the model does.

OpenCode uses Claude Code-compatible Agent Skill folders. Lookup paths (project → global → Claude-compat → Agent-compat):

.opencode/skills/<name>/SKILL.md
~/.config/opencode/skills/<name>/SKILL.md
.claude/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md

Each SKILL.md needs YAML frontmatter with a name (lowercase-kebab, ≤64 chars) and a description (1–1024 chars). The description is the discovery signal — write it like a trigger sentence the agent will recognize.

Command vs. skill, in one line: commands are user-invoked (/<name>), skills are model-invoked (description match). Write both for the same workflow if you want both surfaces.

This repo ships one example: .opencode/skills/git-release/SKILL.md.

📚 Deep dive: docs/skills.md · opencode.ai/docs/skills.

Plugins

Mental model: Plugins are OpenCode's event-driven extension surface — small JavaScript or TypeScript modules that subscribe to lifecycle events (tool calls, file edits, session state) and run code automatically. husky for your AI session.

Two locations:

.opencode/plugins/<name>.{js,ts}                    # project
~/.config/opencode/plugins/<name>.{js,ts}           # global

Plus npm packages via the plugin array in opencode.json:

{ "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"] }

Auto-installed via Bun, cached under ~/.cache/opencode/node_modules/.

Plugins receive { project, directory, worktree, client, $ } and return hooks. $ is the Bun shell. Two shapes: typed hooks like tool.execute.before/shell.env that get (input, output), and a generic event handler for the lifecycle stream (files, sessions, messages, permissions, LSP, TUI — ~26 events).

This repo ships two working examples in .opencode/plugins/:

File	What it does
`protect-secrets.js`	Blocks any tool call touching `.env*`, `secrets/`, SSH keys
`audit-log.js`	Appends every successful tool call to `.opencode/audit.jsonl`

⚠️ Security: Plugins run arbitrary code with your user permissions. Read every third-party plugin before installing — exactly like reviewing a shell script before sourcing.

📚 Deep dive: docs/plugins.md · opencode.ai/docs/plugins.

Agents

OpenCode ships five built-in agents, and you can define your own as markdown files.

Built-in

Agent	Mode	Tools	Reach for it when…
`build`	primary (default)	All	Default daily-driver — implementation, refactors
`plan`	primary	`edit` and `bash` default to `ask`	Read-only-ish analysis, exploration
`general`	subagent	All minus `todowrite`	Multi-step tasks isolated from main session
`explore`	subagent	`read`, `grep`, `glob`, `list`	"Where is X?" code search
`scout`	subagent	`webfetch`, `websearch`, + read tools	External docs and dependency research

Tab cycles primaries. @<name> invokes a subagent.

Custom

Drop a markdown file in .opencode/agents/:

---
description: Senior frontend engineer — Tailwind + React + TypeScript
mode: all
model: anthropic/claude-sonnet-5
permission:
  edit: allow
  bash:
    "*": "ask"
    "pnpm test*": "allow"
    "git status*": "allow"
---

You're a senior frontend engineer working on a React/Tailwind codebase…

Filename → agent name. frontend-engineer.md → @frontend-engineer (subagent) or in the Tab cycle (primary). The mode value picks the surface:

`mode`	Where it appears
`primary`	Tab cycle alongside `build` / `plan`
`subagent`	`@<name>` mentions only (runs in a child session)
`all`	Both

Bash permissions accept a glob-pattern map ({"*": "ask", "git status*": "allow", "rm -rf*": "deny"}) — rules match in order and the last matching rule wins, so list the catch-all * first.

📐 This repo ships drop-in specialist prompts in specialized-agents/ — backend, frontend, code reviewer, security reviewer, tech lead, database, UX. Copy any of them into .opencode/agents/<name>.md to use.

📚 Deep dive — full frontmatter key list, all 15 permission keys, JSON-form alternative: docs/agents.md · docs/reference/permissions.md.

MCP Servers

MCP is the universal connector that lets OpenCode talk to external tools — browsers, databases, search engines, ticketing systems — through one open protocol. USB-C for AI integrations.

Declare servers in the mcp section of opencode.json. Local servers spawn a subprocess; remote servers hit an HTTPS endpoint with automatic OAuth via Dynamic Client Registration (RFC 7591).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"]
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }
    },
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Manage from the CLI: opencode mcp add | list | auth <name> | logout <name> | debug <name>. Reference a server's tools in a prompt with use <server-name>.

Featured walkthroughs in mcp-servers/:

Server	What it adds
Playwright	Browser automation — DOM, network, screenshots, accessibility
Context7	Live, version-pinned library docs piped into the prompt
Sentry	Errors, traces, releases
Grep by Vercel	Code search across GitHub

⚠️ Token budget: MCP tools land in the model's tool surface every turn — heavy servers can easily eat 10K+ tokens of context. Disable noisy tools with the tools map (e.g. "github_*": false).

📚 Deep dive: docs/mcp.md · opencode.ai/docs/mcp-servers · Registry.

Reference

FAQ

→ Full FAQ in docs/reference/faq.md

Is OpenCode free? The software is open source (MIT). You pay for whichever LLM provider you use. OpenCode Zen is pay-as-you-go per token; OpenCode Go is a flat $10/month for hosted open models; BYOK works for direct providers.

Does OpenCode work without an internet connection? Yes, with a local model (Ollama, LM Studio, llama.cpp). Network is needed for hosted providers, remote MCP servers, sharing, and updates.

Can I migrate from Claude Code? Most concepts map cleanly but a few fields and file paths differ. OpenCode reads CLAUDE.md and .claude/skills/ as fallbacks. Slash commands move from .claude/commands/ → .opencode/commands/; Python hooks become JS/TS plugins; agent frontmatter uses different keys (name gone, mode new, tools becomes permission). See the full migration guide.

Custom commands vs. skills — which should I write? Both. Commands are explicit (user types /<name>); skills are discoverable (model picks them up). Use commands for workflows the user owns, skills for expertise the agent should reach for. Comparison in docs/commands.md.

How do I keep OpenCode from running risky shell commands? Set bash permission to "ask" at the project level, or use the glob form to whitelist only safe patterns. Full mechanism in docs/reference/permissions.md.

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

Current release: v1.17.13 (2026-07-01). Run opencode upgrade to get it.

New in v1.17:

🆕 Session snapshots & revert (v1.17.11) — roll a session back to an earlier message, including the file changes it made.
🆕 TUI yolo mode (v1.17.12) — auto-approve permission prompts from inside the TUI; plus adaptive thinking for Claude Sonnet 5.
🆕 MCP resources (v1.17.10) — resource template listing and resource-read tools, and MCP server instructions now land in session context. Local servers also gained a cwd option (v1.17.4).
🆕 --mini CLI mode & V2 plugin API (v1.17.10) — a lightweight CLI surface, namespaced plugin hooks, and Effect/Promise plugin support.
⚡ Faster file search (new fff-backed tools), WSL-backed desktop on Windows, and a desktop v2 refresh (Chrome-style tabs, searchable model picker) (v1.17.0–v1.17.13).
⚠️ Deprecation: the reference config key is now references (v1.17.1; old entries still load).

Still recent (v1.16):

File-based agents & skill discovery — drop-in agent markdown files and SKILL.md discovery are GA; scaffold an agent with opencode agent create.
Workspace cloning & session mobility — managed workspace clones keep dirty/untracked files; move sessions between workspaces and directories.
opencode run --replay — interactively replay a run as it streams.
~38% faster startup, OpenAI models via AWS Bedrock, GitHub Copilot usage tracking.
📝 AGENTS.md is canonical; CLAUDE.md is a fallback only.

💡 Source of truth: GitHub releases.

References

→ Full reading list in docs/reference/further-reading.md

Most-clicked starting points:

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; wider tables read best on desktop.

Features, pricing, and availability change frequently. Always check the official OpenCode documentation for the most current information.

Last reviewed 2026-07-05 · OpenCode v1.17.13 · Spotted something stale? Open an issue or send a PR — see CONTRIBUTING.md.

Found this useful? Give it a ⭐ — it's how other developers discover the guide.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
.opencode		.opencode
Images		Images
docs		docs
mcp-servers		mcp-servers
specialized-agents		specialized-agents
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
opencode.json		opencode.json
tui.json		tui.json

Folders and files

Latest commit

History

Repository files navigation

OpenCode Primer

🧭 Choose your path

Getting started

What is OpenCode?

When OpenCode isn't the right tool

Setup

1. Install

2. Authenticate

3. First prompt

4. Generate an AGENTS.md

5. (Bonus) See a real configured project

Models & Providers

Direct provider config

OpenCode Zen

OpenCode Go

Using OpenCode

Prompt Engineering

Plan → Build cycle

File references and shell

AGENTS.md for project rules

TUI & Themes

Leader key

Themes

Headless & CI

Sharing

Extending OpenCode

Slash Commands

Custom Commands

Agent Skills

Plugins

Agents

Built-in

Custom

MCP Servers

Reference

FAQ

Updates & Deprecations

References

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

4. Generate an `AGENTS.md`

`AGENTS.md` for project rules

Packages