This guide helps you migrate from Claude Code to OpenCode while using the ECC configuration.

OpenCode is an alternative CLI for AI-assisted development that supports all the same features as Claude Code, with some differences in configuration format.

OpenCode fully supports hooks via its plugin system, which is actually MORE sophisticated than Claude Code with 20+ event types.

Claude Code hook (hooks.json):

{
  "PostToolUse": [{
    "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
    "hooks": [{
      "type": "command",
      "command": "prettier --write \"$file_path\""
    }]
  }]
}

OpenCode plugin (.opencode/plugins/prettier-hook.ts):

export const PrettierPlugin = async ({ $ }) => {
  return {
    "file.edited": async (event) => {
      if (event.path.match(/\.(ts|tsx|js|jsx)$/)) {
        await $`prettier --write ${event.path}`
      }
    }
  }
}

The ECC OpenCode configuration includes translated hooks:

# Install OpenCode CLI
npm install -g opencode
# or
curl -fsSL https://opencode.ai/install | bash

The .opencode/ directory in this repository contains the translated configuration:

.opencode/
├── opencode.json              # Main configuration
├── plugins/                   # Hook plugins (translated from hooks.json)
│   ├── ecc-hooks.ts           # All ECC hooks as plugins
│   └── index.ts               # Plugin exports
├── tools/                     # Custom tools
│   ├── run-tests.ts           # Run test suite
│   ├── check-coverage.ts      # Check coverage
│   └── security-audit.ts      # npm audit wrapper
├── commands/                  # All 23 commands (markdown)
│   ├── plan.md
│   ├── tdd.md
│   └── ... (21 more)
├── prompts/
│   └── agents/                # Agent prompt files (12)
├── instructions/
│   └── INSTRUCTIONS.md        # Consolidated rules
├── package.json               # For npm distribution
├── tsconfig.json              # TypeScript config
└── MIGRATION.md               # This file

# In the repository root
opencode

# The configuration is automatically detected from .opencode/opencode.json

Claude Code:

---
name: planner
description: Expert planning specialist...
tools: ["Read", "Grep", "Glob"]
model: opus
---

You are an expert planning specialist...

OpenCode:

{
  "agent": {
    "planner": {
      "description": "Expert planning specialist...",
      "mode": "subagent",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "{file:prompts/agents/planner.txt}",
      "tools": { "read": true, "bash": true }
    }
  }
}

Claude Code:

---
name: plan
description: Create implementation plan
---

Create a detailed implementation plan for: {input}

OpenCode (JSON):

{
  "command": {
    "plan": {
      "description": "Create implementation plan",
      "template": "Create a detailed implementation plan for: $ARGUMENTS",
      "agent": "planner"
    }
  }
}

OpenCode (Markdown - .opencode/commands/plan.md):

---
description: Create implementation plan
agent: everything-claude-code:planner
---

Create a detailed implementation plan for: $ARGUMENTS

Claude Code: Skills are loaded from skills/*/SKILL.md files.

OpenCode: Skills are added to the instructions array:

{
  "instructions": [
    "skills/tdd-workflow/SKILL.md",
    "skills/security-review/SKILL.md",
    "skills/coding-standards/SKILL.md"
  ]
}

Claude Code: Rules are in separate rules/*.md files.

OpenCode: Rules can be consolidated into instructions or kept separate:

{
  "instructions": [
    "instructions/INSTRUCTIONS.md",
    "rules/common/security.md",
    "rules/common/coding-style.md"
  ]
}

After migration, ALL 23 commands are available:

The .opencode/ directory contains everything pre-configured.

npm install ecc-universal

Then in your opencode.json:

{
  "plugin": ["ecc-universal"]
}

This only loads the published ECC OpenCode plugin module (hooks/events and exported plugin tools). It does not automatically inject ECC's full agent, command, or instructions config into your project.

If you want the full ECC OpenCode workflow surface, use the repository's bundled .opencode/opencode.json as your base config or copy these pieces into your project:

• .opencode/commands/
• .opencode/prompts/
• .opencode/instructions/INSTRUCTIONS.md
• the agent and command sections from .opencode/opencode.json

1. Verify .opencode/opencode.json exists in the repository root
2. Check JSON syntax is valid: cat .opencode/opencode.json | jq .
3. Ensure all referenced prompt files exist

1. Verify plugin file exists in .opencode/plugins/
2. Check TypeScript syntax is valid
3. Ensure plugin array in opencode.json includes the path

1. Check the agent is defined in opencode.json under the agent object
2. Verify the prompt file path is correct
3. Ensure the prompt file exists at the specified path

1. Verify the command is defined in opencode.json or as .md file in .opencode/commands/
2. Check the referenced agent exists
3. Ensure the template uses $ARGUMENTS for user input
4. If you installed only plugin: ["ecc-universal"], note that npm plugin install does not auto-add ECC commands or agents to your project config

1. Start Fresh: Don't try to run both Claude Code and OpenCode simultaneously
2. Check Configuration: Verify opencode.json loads without errors
3. Test Commands: Run each command once to verify it works
4. Use Plugins: Leverage the plugin hooks for automation
5. Use Agents: Leverage the specialized agents for their intended purposes

If you need to switch back:

1. Simply run claude instead of opencode
2. Claude Code will use its own configuration (CLAUDE.md, plugin.json, etc.)
3. The .opencode/ directory won't interfere with Claude Code

For issues specific to:

• OpenCode CLI: Report to OpenCode's issue tracker
• ECC Configuration: Report to github.com/affaan-m/ECC