mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-19 02:17:58 +00:00
- 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.
229 lines
9.1 KiB
Markdown
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/).*
|