My Claude Code setup was small, which is exactly why its failure surprised me. One root CLAUDE.md. A MEMORY.md beside it. A folder of reference docs, and a second CLAUDE.md doing the job of a rules file. It hummed along for months. Then, with no changes at all, it started leaking.
Claude mixed up the files — rules surfaced as instructions, memory got treated as reference material — and I watched my token count climb on every session. I hadn't touched anything. That was the most frustrating part: it proved the setup had been fragile from day one; the cracks just took months to show.
So I moved. Both feet. I brought every file to OpenCode and started talking to it. It remembered me. It ignored my instructions.
This is what broke after that — ranked, with the rebuild for each one. The short version: the migration isn't a file copy, it's a re-declaration.
What broke, ranked in the order it hurt
The list is ranked by how much each break cost me, not by how loud it was. The quiet ones hurt the most.
Break 1 — My instructions didn't come with me
OpenCode had my memory loaded — it referenced my notes and conventions from MEMORY.md correctly. But my rules from CLAUDE.md weren't in effect. Whether that April version of OpenCode never loaded the file, or loaded it and ignored it, the outcome was identical: my instructions weren't being followed.
The reason became obvious once I stopped to think: CLAUDE.md is Claude's rule file. OpenCode reads AGENTS.md.
On paper that's a one-line rename. In practice it was the first confirmation that this migration was a translation, and the translation work landed on me — not the tool.
The rebuild: re-declare your rules in AGENTS.md. Don't copy — re-declare, because some of what your old rules assumed is now load-bearing. Then verify the rules are actually in effect. Run /init (OpenCode reads CLAUDE.md and seeds AGENTS.md from it — docs), then ask the agent in a fresh session: "what are my rules?" If it can't quote them, they're not loaded. Loaded is not the same as obeyed.
Break 2 — I asked OpenCode to migrate its own predecessor's config
I treated the migration as "bring the files, tell the new agent what I had." Then I went one step further: I asked OpenCode to migrate my skills and MCP servers for me.
The problem with asking a tool to migrate its own predecessor's tooling: it doesn't know what it doesn't know. It can't inventory what it never had. It has no idea which of my skills were load-bearing, which MCPs I used once and forgot, or where the config actually lived. It told me what it could — and couldn't tell me what was missing, because the missing stuff never existed in its world.
The rebuild: inventory first. Before you touch the new tool, list every skill, command, and MCP server you actually use. Write them down while the old tool is still alive to ask. Then decide consciously what gets rebuilt versus what gets dropped. The list is the migration plan — without it, you're migrating whatever happens to survive.
Break 3 — What did migrate degraded silently
The skills that did make it over didn't behave the same. OpenCode read them but ignored chunks of their frontmatter — model assignments, allowed tools, argument handling. And it didn't auto-fire them the way Claude Code did; skills load on demand here, when the agent decides to reach for them.
Nothing errored loudly. They just worked less. That's the worst kind of break: the silent one, because it doesn't surface until you trust the skill and it quietly does the wrong thing.
This one is even documented: OpenCode only recognizes name, description, license, compatibility, and metadata in a skill's frontmatter (skills docs). Everything else is silently ignored.
The rebuild: assume every ported skill is degraded until proven otherwise. Rebuild the ones you actually use and delete the rest (more on this in the "rebuild, don't port" section).
Break 4 — The friction tax
Manually toggling between plan and build modes with Tab, instead of Claude Code's automatic transition. Different keybinds. Different scroll behavior. None of it is a bug — but it's a constant low-grade "this feels wrong" that lasts for the first few weeks.
This one never shows up in migration guides, because it never shows up in a feature table. It's a tax, not a defect.
The rebuild: budget the adjustment period like you'd budget a learning curve — plan on two to three weeks of reduced flow, not two days. On day one, map your three most-used Claude Code keybinds to their OpenCode equivalents. Force yourself through the change instead of reaching for the old muscle memory.
Break 5 — The one that didn't break for me, but will for you: no auto-memory
OpenCode has no native cross-session memory. No silent "remembers what you said last week" like Claude Code has. There's an open feature request for it (#20322), and it's not shipped.
My MEMORY.md survived the migration because it was a file. Yours might not be. If you've been relying on the agent just remembering things across sessions, that memory evaporates the day you switch.
The rebuild: give the agent a session log. Add one instruction to AGENTS.md:
## Session log
At the end of every session, append a short summary to `session-log.md`:
what was done, what's pending, and any decisions made. Never lose a decision.
That one instruction replaced the silent memory I lost — and made my memory better, because now it's explicit, greppable, and portable to whatever tool I use next.
What I gained (the counterweight)
A list of four breaks with no counterweight is a hit piece. Here's the honest other half.
Permission-first by default. OpenCode runs on my hardware — I bring my own keys. And out of the box it asks before acting: it wants to read a folder outside the current directory, it stops and asks. I approve, it proceeds. It rebuilt my trust in the tool faster than any benchmark table could. The honest limits: inside the working directory it's permissive by default, and .env files are denied by default — which is the right default. And keep it updated: the 2026-22812 and 22813 CVEs were patched, and a stale harness is the one risk in an otherwise local-first setup.
One key, many models. My setup is deliberately boring: the built-in model plus a single API key for OpenRouter. One key, dozens of models. Switching models for a task is a config line — not a harness, not a subscription, not a signup flow. After Claude Code, where the model was whatever Anthropic shipped, that felt like the ceiling coming off.
Cost reality. January 9, 2026 is a date a lot of us remember — the day Anthropic restricted third-party tools from using Claude subscription OAuth, with a full cutoff that April. It was the day my project stalled: I sat down to continue work I'd started two or three weeks earlier and couldn't do a thing. A workday gone, a project stuck, and a subscription that no longer worked the way I'd paid for it. On the other side, my token bill became something I could actually reason about instead of a flat subscription that either worked or didn't.
The one lesson that mattered: rebuild, don't port
The inversion that reframed everything: the skills I carried over degraded silently, but a freshly installed skill worked on the first go. No debugging, no frontmatter fighting, no "why won't this load." Drop it in, call it, done.
That flipped how I thought about the whole migration. Don't port your skills — rebuild the ones you actually use.
This applies beyond skills. It applies to rules, memory, and MCP config. And it explains why the ported stuff behaved differently in the first place: the harness matters more than people admit. Same model, different wrapper, measurably different results — in one 2026 benchmark, OpenCode finished in 7 minutes with zero mistakes; Claude Code took 14 minutes and made two, on the same model. Separately, tracker-sourced SWE-bench numbers show a ~3.6-point swing between two harnesses running the same model. The agent is only as good as what's declared to it.
Carry the knowledge. Rebuild the tooling.
Would I do it again? Yes. Here's my day-one do-over
Straight answer: yes. Not once did the breakage list add up to enough to pull me back. Running locally, the permission-first default, a skill workflow that rebuilt better than the original, and the cost — those four outweighed every item on the broke list. That surprised me more than the breaks themselves.
But I'd change day one. In order:
-
Build the
AGENTS.mdfirst — the file that owns the state. Spend the morning on it, not the migration. - Add the session-log instruction ("log what you did each session") so nothing is forgotten and no decision falls through the cracks.
- Rebuild the three skills you actually use. Delete the rest.
- Re-declare MCPs manually. Audit versions before you trust them.
- Decide the model and permission posture consciously — what you run, where you keep keys, where you let it read.
Most of what broke in my migration wasn't the tooling. It was that my knowledge lived in places the new tool couldn't read. The fix isn't a better importer. It's one file that owns the state, written from day one.
Migrate if / stay if
- Migrate if you want multi-provider freedom or local models; you're burned by subscription-OAuth economics; you value a permission-first workflow; you're willing to re-declare your rules instead of copying them.
- Stay if you're maximally invested in Claude's ecosystem — skills, hooks, auto-memory; you want speed and polish out of the box; you're happy on a flat subscription; you can't spend the adjustment weeks.
- Or run both. The honest middle option: Claude Code for fast interactive work, OpenCode for provider experiments. Several reviewers recommend exactly this, and nothing about my migration contradicts it.
Don't do these (the checklist)
- Copying files instead of re-declaring rules. Migration is re-declaration, not a file copy.
- Trusting "drop-in / full parity" claims. Real parity needs wrappers, plugins, and manual re-declaration.
- Assuming rules are in effect because the file loaded. Loaded ≠ obeyed. Verify.
- Asking the new agent to migrate the old config. It can't inventory what it never had.
- Ignoring the cost shift: per-token models, prompt-cache misses, and the new subscription math.
- Skipping the security and version audit. The 2026-22812/22813 CVEs were patched; keep it updated.
The verdict
Four breaks, four wins, no regrets. Everything that broke traced back to the same root: the knowledge was there, it just lived in a place the new tool couldn't read. And the fix was the same for every single one of them — declare it, and log it.
The migration wasn't about which harness is better. It was about making my workflow portable on purpose. That's the only way a migration sticks — whether you move now, later, or never.
FAQ
Does OpenCode read CLAUDE.md?
OpenCode reads AGENTS.md. CLAUDE.md is only used as a fallback when no AGENTS.md exists — which is why copying your CLAUDE.md over and expecting your rules to work is the #1 migration mistake. Re-declare them.
Do my Claude Code skills work in OpenCode?
Partially. OpenCode only recognizes name, description, license, compatibility, and metadata in a skill's frontmatter — everything else is silently ignored, and skills load on demand rather than auto-firing. Rebuild the ones you actually use.
Does OpenCode have auto-memory like Claude Code?
No native cross-session memory (feature request #20322 is open). Add a session-log instruction to AGENTS.md so nothing is forgotten between sessions.
Is migrating worth it?
If you want provider freedom, local-first operation, and a permission-first workflow — yes. If you're maximally invested in Claude's ecosystem (hooks, auto-memory, flat subscription) — stay, or run both.
Can I use the same model in both?
Yes — OpenCode supports 75+ providers including Anthropic and OpenRouter, so you can A/B test the harness effect with the same model.
If you've been fighting the same battle — instructions that aren't followed, memory that disappears between sessions — I wrote the full playbook for fixing it here: Why Your Coding Agent Keeps Making the Same Mistakes — AGENTS.md Fixes It.
What broke when you migrated? Name the one thing you lost that nobody warned you about — and if nothing broke, tell me that too, especially where I'm wrong. I'll collect the rebuilds people reply with in a follow-up.
This is the first post in my agent-workflow migration series.
Top comments (1)
One thing I left out of the post: the first two weeks, every time something felt even slightly off, my brain jumped straight to "Claude Code didn't do this." It was never actually true — it was the friction tax making me second-guess the switch. The instinct faded by week three.
So now I'm curious: what's the one thing that still makes you doubt your current tool — even when you know the switch was right? Name it, and I'll collect the honest ones for the follow-up post.