Files
opencode-primer/docs/migration.md
T
Wesam Abousaid 9522c859fd docs(guides): add 10 deep-dive guides verified against opencode.ai/docs
- quickstart.md: 5-minute path from curl to first commit
- zen.md: model gateway with full lineup, pricing, BYOK, patterns
- tui.md: keybinds, leader chords, themes, customization, sessions
- agents.md: custom agents and subagents, full frontmatter, permission map
- commands.md: custom slash commands, placeholders, patterns, override rules
- skills.md: discoverable workflows, SKILL.md format, description-as-trigger
- plugins.md: lifecycle hooks, full event catalog, four real patterns
- mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers,
  with mermaid N×M → N+M diagram
- migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does
  better" subsections so the comparisons aren't one-sided
- workflows.md: seven real recipes (TDD, bug investigation, multi-agent
  review, cross-repo research, migrations, CI, visual iteration) — CI
  example shows GitHub Actions + GitLab CI to avoid platform bias

Every model slug, permission key, config key, env var, and CLI flag
verified against the JSON schema or the live docs site.
2026-05-18 19:59:28 +02:00

229 lines
9.1 KiB
Markdown

# 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.md` folders)
- 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
```bash
# 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:
```yaml
---
name: code-reviewer
description: ...
tools: Read, Grep, Glob, Bash
model: sonnet
---
```
OpenCode uses:
```yaml
---
description: ...
mode: subagent
model: anthropic/claude-sonnet-4-5
permission:
edit: deny
bash: ask
---
```
Key changes:
- No `name` field — filename is the name.
- `tools` becomes either the `tools` map (`{"bash": true}`) or the `permission` map (`{"bash": "allow"}`).
- `model` is `provider/model-id`, not a shorthand.
- Add `mode: subagent` (or `primary` / `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`:
```python
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`):
```javascript
export const ProtectEnv = async () => {
return {
event: async ({ event }) => {
if (event.type === "tool.execute.before" && event.tool === "edit") {
if ((event.input?.path ?? "").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:
```json
{
"$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.
```bash
curl -fsSL https://opencode.ai/install | bash
opencode auth login
cd ~/your-project && opencode
```
## From Aider
[Aider](https://aider.chat/) 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
1. Run `/init` to refresh your `AGENTS.md` — OpenCode reads it slightly differently and `/init` will populate the canonical sections (commands, conventions, repo layout).
2. Browse this repo's [`.opencode/`](../.opencode/) for example agent, command, and skill formats.
3. 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" }`).
4. Set `OPENCODE_DISABLE_CLAUDE_CODE=1` to stop the `CLAUDE.md` fallback once you've fully renamed to `AGENTS.md`.
---
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*