Imported from CengizKuscu/claude-to-opencode (AGENTS.md). Install upstream with npx skills add CengizKuscu/claude-to-opencode. Copyright stays with the author.

AGENTS.md

Project

CLI tool (claude-to-opencode) that migrates Claude Code projects to OpenCode format. TypeScript, compiled to dist/, no test suite, no linter configured.

Commands

npm run build   # tsc → dist/  (only build step; required before running)
npm run dev     # ts-node src/index.ts (run from source without build)
node dist/index.js --input <path> --output <path>

There is no test, lint, or typecheck script beyond tsc (which is npm run build). Always run npm run build after editing source before testing changes via node dist/index.js.

Source layout

src/
  index.ts              # CLI entry (commander), orchestrates all converters
  types.ts              # All shared interfaces — single source of truth for data shapes
  scanner/scanner.ts    # Scans input project, returns ScanResult
  frontmatter/
    transformer.ts      # All frontmatter conversion logic (model map, tool→permission, etc.)
  converters/
    agents.ts           # .claude/agents/*.md → .opencode/agents/*.md
    commands.ts         # .claude/commands/*.md → .opencode/commands/*.md
    skills.ts           # .claude/skills/*/SKILL.md → .opencode/skills/*/SKILL.md
    claude-md.ts        # CLAUDE.md @include inlining
    mcp.ts              # .mcp.json + .claude/settings.json → opencode.json
    rules.ts            # path-scoped rules → _unsupported/rules/
    hooks.ts            # hooks → _unsupported/hooks/
  report/reporter.ts    # Generates MIGRATION-REPORT.md
  utils/
    fs.ts               # Async file helpers (exists, readFile, listFiles, listDirs)
    logger.ts           # Logger factory (verbose/dry-run aware)

Key conventions

• frontmatter/transformer.ts is the central logic file — model alias maps, tool-to-permission mappings, and all frontmatter conversion functions live there. Add new mappings here first.
• TOOL_KEY_MAP in transformer.ts maps Claude tool names (e.g. Write, Bash) to OpenCode permission keys (e.g. edit, bash). Update this when adding new tool support.
• MODEL_MAP in transformer.ts maps Claude model aliases per provider. Currently covers anthropic, openai, google.
• Converters receive (scan, options, result, log?) — they mutate result in place (counts, warnings, errors, unsupportedFiles).
• Dry-run: all file writes must go through the logger/fs utilities that check options.dryRun. Never call fs.writeFile directly in a converter.
• Skills have a non-obvious structure: each skill is a subdirectory with a SKILL.md inside, not a flat .md file. Subdirectory name becomes the skill name.

OpenCode format constraints (verified against docs)

Skill frontmatter

OpenCode skills only accept these frontmatter fields: name, description, license, compatibility, metadata. There is no tools or permission field in skill frontmatter. The convertSkillFrontmatter function in transformer.ts correctly drops allowed-tools with a warning instead of mapping it.

Agent frontmatter

The tools field in agent config is deprecated in OpenCode — use permission instead. The converter already emits permission: { edit: "deny", bash: "deny" } style output. Agent mode defaults to all if omitted, but the converter always sets it explicitly.

Permission format

Permissions use "allow" / "deny" / "ask" strings. For bash sub-patterns: { bash: { "git *": "allow" } }. Last matching rule wins.

MCP format

.mcp.json mcpServers[name].command + args → OpenCode mcp[name].command (single array). env → environment. Remote servers need type: "remote" + url.

CLAUDE.md includes

OpenCode does not natively parse @filepath includes — converter inlines them directly into the output file. This is intentional: OpenCode uses opencode.json instructions array for multi-file instructions instead.

Unsupported content handling

• Hooks and path-scoped rules cannot be converted; they are copied to _unsupported/ (or just reported) depending on --unsupported flag (copy-and-report default, report-only).
• UnsupportedFile entries are pushed to result.unsupportedFiles and appear in the generated MIGRATION-REPORT.md.

Binary / entry point

• package.json bin points to dist/index.js — file must be compiled before npm link or direct invocation works.
• npm link makes claude-to-opencode available globally from the compiled output.