Update the guide to the current release (v1.16.2, 2026-06-05), verified against opencode.ai/docs and github.com/anomalyco/opencode. Correctness fixes: - Plugins: tool.execute.before/after and shell.env are top-level hooks with an (input, output) signature, not event.type values. Rewrite both shipped example plugins plus the docs/migration examples so they fire. - Permissions: bash glob maps resolve last-matching-rule-wins (catch-all "*" first), not most-specific-wins. Fix prose, reorder examples, and fix the shipped opencode.json (rm -rf* deny was shadowed by a later rm *). - Drop non-existent permission keys repo_clone/repo_overview (15 keys, not 17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort into model options; fix the `mise` install command. Currency updates: - v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section. - Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4, gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs). - Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and native GitHub commands; correct the specialist-prompt count; bump dates. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9.3 KiB
Migration Guide
Switching from another AI coding tool to OpenCode. Concrete mappings, no marketing.
Before reading this, a fair note: none of the tools below is universally better. This guide is about migrating to OpenCode, which makes sense if its trade-offs (open source, multi-provider, terminal-first, configurable) line up with what you want. If you're happy on Claude Code, Cursor, Copilot, or Aider, those are good tools — keep using them.
From Claude Code
OpenCode has shape compatibility with Claude Code — similar concepts, similar file layouts, fallback support for CLAUDE.md and .claude/skills/ — but it isn't a literal drop-in. Frontmatter keys differ on agents, hooks become JS/TS plugins, and the CLI surface is its own. Plan to spend ~30 minutes adapting a non-trivial Claude Code project.
What Claude Code does better
- Tighter Anthropic integration. First-party support for Claude-specific features (extended thinking, prompt caching tuning, etc.) lands in Claude Code first and is more battle-tested there.
- Single-vendor polish. One company owns the model, the CLI, and the docs — fewer rough edges where layers meet.
- Subscription pricing can be more predictable than pay-as-you-go if you're a heavy user.
If those matter more to you than multi-provider flexibility or full open source, staying on Claude Code is reasonable.
What's the same
- Terminal-first interaction model
@<path>for file references!<cmd>for shell injection- Slash commands (
/init,/help,/share,/export, etc.) - Custom commands as markdown files
- Agent Skills (
SKILL.mdfolders) - MCP server support (same protocol)
What's different
| Claude Code | OpenCode |
|---|---|
| Anthropic models only | Any provider (Anthropic, OpenAI, Google, Groq, Bedrock, local…) via Zen or direct config |
| Subscription pricing (Pro/Max) | Pay-as-you-go via Zen, or your own provider's billing |
CLAUDE.md for project rules |
AGENTS.md (falls back to CLAUDE.md for compatibility) |
.claude/commands/<name>.md |
.opencode/commands/<name>.md |
.claude/skills/<name>/SKILL.md |
.opencode/skills/<name>/SKILL.md (but also reads from .claude/skills/) |
.claude/settings.json hooks (Python scripts on lifecycle events) |
.opencode/plugins/<name>.{js,ts} (JS/TS modules on events) |
.claude/agents/<name>.md |
.opencode/agents/<name>.md (similar markdown+YAML format, different fields) |
claude CLI |
opencode CLI |
/auth login |
opencode auth login or /connect |
Migration steps
# 1. Install
curl -fsSL https://opencode.ai/install | bash
# 2. Authenticate
opencode auth login # pick a provider (Anthropic, Zen, OpenAI, etc.)
# 3. Move project config
git mv .claude/commands .opencode/commands # if you had commands
git mv .claude/skills .opencode/skills # if you had skills
git mv .claude/agents .opencode/agents # but see agent format note below
mv CLAUDE.md AGENTS.md # rename — OpenCode prefers AGENTS.md
# 4. Disable the Claude fallback once migrated
export OPENCODE_DISABLE_CLAUDE_CODE=1
# Or, if you only want to disable one half of the fallback:
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # ignore CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # ignore .claude/skills/
Agent format differences
Claude Code subagents and OpenCode agents are conceptually the same but use different frontmatter keys. Claude Code uses:
---
name: code-reviewer
description: ...
tools: Read, Grep, Glob, Bash
model: sonnet
---
OpenCode uses:
---
description: ...
mode: subagent
model: anthropic/claude-sonnet-4-5
permission:
edit: deny
bash: ask
---
Key changes:
- No
namefield — filename is the name. toolsbecomes either thetoolsmap ({"bash": true}) or thepermissionmap ({"bash": "allow"}).modelisprovider/model-id, not a shorthand.- Add
mode: subagent(orprimary/all).
Hooks → Plugins
Claude Code uses Python scripts triggered by .claude/settings.json. OpenCode uses JS/TS modules in .opencode/plugins/. Behaviorally similar, syntactically different.
Claude Code pre_tool_use.py:
import json, sys
event = json.load(sys.stdin)
if event["tool_name"] == "Write" and ".env" in event["tool_input"]["path"]:
print("Blocked: cannot write .env", file=sys.stderr)
sys.exit(2)
OpenCode equivalent (.opencode/plugins/protect-env.js):
export const ProtectEnv = async () => {
return {
// `tool.execute.before` is a top-level hook: (input, output). `input.tool`
// names the tool; `output.args` holds its arguments. Throw to block.
"tool.execute.before": async (input, output) => {
if (input.tool === "edit" || input.tool === "write") {
if ((output?.args?.filePath ?? "").includes(".env")) {
throw new Error("Plugin blocked: cannot write .env");
}
}
},
};
};
From Cursor
Cursor and OpenCode have different surfaces (IDE-embedded vs. terminal-first) but similar AI capabilities.
What's the same
- AI-assisted edits with project context
- File-mention syntax (
@) - Custom rules / project conventions
What's different
| Cursor | OpenCode | |
|---|---|---|
| Surface | VS Code fork (full IDE) | TUI, desktop, or IDE extension — bring your own editor |
| Rules | .cursor/rules/*.md |
AGENTS.md + instructions: ["..."] in opencode.json |
| Workflow | Cursor Composer / Cursor Tab inline | TUI + custom commands |
| Pricing | Subscription | Pay-as-you-go or BYOK |
| Source | Proprietary | MIT open source |
What Cursor does better
- Inline tab-completion is Cursor's bread and butter and is genuinely excellent — OpenCode doesn't have an equivalent.
- Native IDE integration — diff views, refactor previews, multi-file edits live in your editor, no terminal context-switch.
- Onboarding is faster — install the app, sign in, you're productive.
If you write code primarily in a GUI editor and want the AI right there, Cursor is hard to beat.
Importing Cursor rules
You can keep your .cursor/rules/ and reference them from OpenCode:
{
"$schema": "https://opencode.ai/config.json",
"instructions": [".cursor/rules/*.md", "AGENTS.md"]
}
OpenCode glob-expands the patterns and concatenates the content into the system prompt.
From GitHub Copilot
Copilot is autocompletion-first; OpenCode is conversation-first. They serve different (overlapping) jobs.
Mental model shift
| Copilot | OpenCode |
|---|---|
| Inline ghost-text completion in your editor | Full conversation in the terminal |
| Single-file scope by default | Whole-repo grounding by default |
| Code generation | Code generation + reading + editing + running tests + git ops |
| Subscription, IDE-locked | Provider-agnostic, terminal/desktop/IDE |
OpenCode replaces Copilot's kind of help only partially. For inline completion you'd still want Copilot, Cursor Tab, Codeium, or Supermaven. OpenCode is better suited to multi-file edits, refactors, and "do the thing" prompts where the agent runs the loop — but Copilot covers a high-frequency use case (every keystroke) that OpenCode doesn't try to.
Most teams that adopt agent tools run them alongside an autocomplete tool, not instead.
Migration
There's no config to migrate. Install OpenCode alongside Copilot — they don't conflict.
curl -fsSL https://opencode.ai/install | bash
opencode auth login
cd ~/your-project && opencode
From Aider
Aider was an early terminal-AI tool and is still actively maintained. The two tools target the same space with different priorities.
What Aider does better
- Smaller surface area. Aider is a focused Python tool you can read end-to-end. OpenCode has substantially more moving parts.
- Strong git integration. Aider's automatic commit-per-change and git-aware editing workflow is mature.
- Lower setup overhead for users who just want "edit my files with an LLM."
OpenCode adds skills, plugins, MCP, subagents, themes, a desktop app, and a headless server. Whether that's an upgrade or scope creep depends on what you actually need.
Mapping
| Aider | OpenCode |
|---|---|
.aider.conf.yml |
opencode.json |
.aider.chat.history.md |
OpenCode session persistence (/sessions) |
Aider's /run |
OpenCode's !cmd prefix or bash tool |
Aider's --edit-format modes |
OpenCode's edit / write / apply_patch tools |
Aider's --read files |
OpenCode's @<path> references |
Migration is mostly muscle-memory adjustment, not config porting.
After migration
- Run
/initto refresh yourAGENTS.md— OpenCode reads it slightly differently and/initwill populate the canonical sections (commands, conventions, repo layout). - Browse this repo's
.opencode/for example agent, command, and skill formats. - Audit your old hooks/scripts for things that should become plugins versus things that should become agent permission rules (a lot of "block X" hooks are simpler as
bash: { "X*": "deny" }). - Set
OPENCODE_DISABLE_CLAUDE_CODE=1to stop theCLAUDE.mdfallback once you've fully renamed toAGENTS.md.
Last reviewed: 2026-06-08 · Canonical source: opencode.ai/docs.