Developer moved a months-old Claude Code workflow to OpenCode and discovered that file handling, rule loading, tool inventory, skill metadata and cross-session memory all fell apart. The fixes he documented now serve as a practical checklist for anyone shifting from Claude’s ecosystem to the open-source alternative.

Why the migration mattered

Claude Code users depend on a tightly bundled set of files—rules, skill definitions and memory logs—to keep an AI-driven coding assistant running smoothly. When the author’s setup stopped loading rules, mixed up files and saw token usage spike, his daily coding helper became unreliable. OpenCode promises “permission-first security”, model-agnostic access via OpenRouter and pay-as-you-go pricing, making it attractive. But the transition isn’t a simple copy-paste; you must re-declare every component in the format OpenCode expects.

What led to the breakage

Claude Code used a file called CLAUDE.md, which OpenCode ignores and instead reads AGENTS.md for additional metadata. The author assumed the two systems were interchangeable, leaving several core pieces invisible to OpenCode.

The concrete failures and how to fix them

  • Rules file ignored
    OpenCode never reads CLAUDE.md; it only parses AGENTS.md. Renaming the file isn’t enough because the content must be re-declared in the new format.
    Fix: Create a fresh AGENTS.md, copy the rule text, start a new OpenCode session and ask the agent “What are my rules?” If it can’t quote them, the rules haven’t loaded.

  • Tooling inventory missing
    The migration command that was supposed to copy skills and MCP (multi-cloud platform) servers failed because OpenCode cannot inventory tools that were never registered.
    Fix: While Claude Code tools are still running, list every skill and command manually. Decide which ones to rebuild in OpenCode and which to drop.

  • Front-matter stripped from skills
    Ported skill files lost most of their front-matter, including model assignments and tool handling directives. OpenCode only respects a handful of fields, so the imported skills behaved unpredictably.
    Fix: Treat every imported skill as broken. Re-create the three most-used skills from scratch, ensuring they contain only the supported fields. Delete any unused skill files.

  • No cross-session memory
    Claude Code kept a persistent history that the author relied on for context. OpenCode does not maintain memory across sessions, so the assistant “forgot” everything the day after the switch.
    Fix: Add an explicit instruction to AGENTS.md: “At the end of every session, append a short summary to session-log.md covering what was done, what is pending, and decisions made.” The session log then becomes the single source of truth for continuity.

The stakes: what you win and what you lose

Wins

  • Permission-first security: OpenCode asks before executing any action, reducing accidental code changes.
  • Model freedom: A single API key unlocks dozens of models through OpenRouter, letting you experiment without changing configuration files.
  • Cost control: Billing is usage-based, avoiding the flat-rate subscription that can become expensive when token consumption spikes.

Losses

  • No built-in long-term memory means you must maintain a manual log.
  • Limited skill metadata forces you to rebuild most of your custom tools.

A practical migration checklist

  1. Create AGENTS.md first – declare every rule you need before importing any other files.
  2. Add a session-log instruction – embed the “append summary” rule at the top of AGENTS.md.
  3. Rebuild top three skills – copy only the supported fields; test each skill in isolation.
  4. Manually re-declare MCPs – list each server or cloud endpoint you still need to reach.
  5. Validate – start a fresh OpenCode session and query the assistant for its rules, skill list and memory status.

Takeaway

Migrating from Claude Code to OpenCode is less about moving files and more about re-architecting the declarations that drive the assistant. The process forces you to strip down to core rules, rebuild essential skills and adopt a manual memory log, but it also opens the door to cheaper, model-agnostic AI assistance. If you’re ready to trade convenience for control, follow the checklist above and treat every imported component as a fresh start.