oh-my-claudecode-opencode 0.4.0 → 0.5.0

package/README.md

@@ -8,6 +8,41 @@ Like Sisyphus condemned to roll his boulder eternally, this plugin ensures your
 
 ---
 
+## 🚀 Quick Install
+
+### For Humans (Recommended)
+
+Just tell your AI assistant:
+
+> **"Install oh-my-claudecode-opencode by following these instructions: https://raw.githubusercontent.com/devswha/oh-my-claudecode-opencode/main/docs/guide/installation.md"**
+
+That's it. The AI will handle the rest.
+
+### One-liner (If you insist on doing it yourself)
+
+```bash
+cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest && cat > opencode.json << 'EOF'
+{
+  "plugin": ["oh-my-claudecode-opencode"]
+}
+EOF
+echo "✅ Restart OpenCode to activate OMCO"
+```
+
+### Magic Keywords
+
+Once installed, just include these keywords in your prompts:
+
+| Keyword | Effect |
+|---------|--------|
+| `ultrawork` or `ulw` | Maximum intensity parallel execution |
+| `ralph` | Persistence mode - won't stop until complete |
+| `autopilot` | Full autonomous execution |
+
+Example: `ulw implement user authentication with tests`
+
+---
+
 ## 🎯 What is this?
 
 This project **ports the powerful features** of [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) v3.3.6 (a Claude Code plugin) to the **OpenCode platform**.
@@ -67,25 +102,27 @@ This project **ports the powerful features** of [oh-my-claudecode](https://githu
 
 ## Installation
 
-```bash
-# Using npm
-npm install oh-my-claudecode-opencode
-
-# Using bun
-bun add oh-my-claudecode-opencode
+> 💡 **Recommended**: Let your AI handle it! See [Quick Install](#-quick-install) above.
 
-# Using pnpm
-pnpm add oh-my-claudecode-opencode
-```
+### Manual Installation
 
-Then add to your OpenCode configuration:
+```bash
+# Install in OpenCode config directory
+cd ~/.config/opencode
+npm install oh-my-claudecode-opencode
 
-```json
+# Register plugin in opencode.json
+cat > opencode.json << 'EOF'
 {
-  "plugins": ["oh-my-claudecode-opencode"]
+  "plugin": ["oh-my-claudecode-opencode"]
 }
+EOF
+
+# Restart OpenCode to activate
 ```
 
+For detailed instructions, see [Installation Guide](docs/guide/installation.md).
+
 ## Usage
 
 ### Ultrawork Mode
@@ -388,6 +425,44 @@ When triggered:
 3. Minimizes confirmation requests
 4. Maximizes throughput
 
+## Troubleshooting
+
+### Agents not showing in Tab menu?
+
+Run the diagnostic tool:
+
+```bash
+npx oh-my-claudecode-opencode doctor
+```
+
+This checks:
+1. Plugin installation in `~/.config/opencode/node_modules/`
+2. Plugin registration in `opencode.json`
+3. Asset files present
+4. Package dependencies
+5. OMCO configuration validity
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Plugin not installed" | `cd ~/.config/opencode && npm install oh-my-claudecode-opencode` |
+| "Plugin not in opencode.json" | Add `"oh-my-claudecode-opencode"` to `"plugin"` array |
+| "Assets directory missing" | Reinstall: `npm install oh-my-claudecode-opencode@latest` |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed |
+| 1 | Critical failure found |
+| 2 | Warnings only |
+
+### Getting Help
+
+1. Run `/doctor` in OpenCode and share the report
+2. Open an issue: https://github.com/devswha/oh-my-claudecode-opencode/issues
+
 ## Development
 
 ```bash

package/assets/skills/doctor.md

@@ -1,192 +1,88 @@
 ---
 name: doctor
-description: Diagnose and fix oh-my-claudecode installation issues
+description: Diagnose and fix OMCO installation issues for OpenCode
 user-invocable: true
 ---
 
-# Doctor Skill
+# Doctor Skill (OpenCode)
 
-## Task: Run Installation Diagnostics
+## Quick Diagnosis
 
-You are the OMC Doctor - diagnose and fix installation issues.
-
-### Step 1: Check Plugin Version
-
-```bash
-# Get installed version
-INSTALLED=$(ls ~/.claude/plugins/cache/omc/oh-my-claudecode/ 2>/dev/null | sort -V | tail -1)
-echo "Installed: $INSTALLED"
-
-# Get latest from npm
-LATEST=$(npm view oh-my-claudecode version 2>/dev/null)
-echo "Latest: $LATEST"
-```
-
-**Diagnosis**:
-- If no version installed: CRITICAL - plugin not installed
-- If INSTALLED != LATEST: WARN - outdated plugin
-- If multiple versions exist: WARN - stale cache
-
-### Step 2: Check for Legacy Hooks in settings.json
-
-Read `~/.claude/settings.json` and check if there's a `"hooks"` key with entries like:
-- `bash $HOME/.claude/hooks/keyword-detector.sh`
-- `bash $HOME/.claude/hooks/persistent-mode.sh`
-- `bash $HOME/.claude/hooks/session-start.sh`
-
-**Diagnosis**:
-- If found: CRITICAL - legacy hooks causing duplicates
-
-### Step 3: Check for Legacy Bash Hook Scripts
-
-```bash
-ls -la ~/.claude/hooks/*.sh 2>/dev/null
-```
-
-**Diagnosis**:
-- If `keyword-detector.sh`, `persistent-mode.sh`, `session-start.sh`, or `stop-continuation.sh` exist: WARN - legacy scripts (can cause confusion)
-
-### Step 4: Check CLAUDE.md
-
-```bash
-# Check if CLAUDE.md exists
-ls -la ~/.claude/CLAUDE.md 2>/dev/null
-
-# Check for OMC marker
-grep -q "oh-my-claudecode Multi-Agent System" ~/.claude/CLAUDE.md 2>/dev/null && echo "Has OMC config" || echo "Missing OMC config"
-```
-
-**Diagnosis**:
-- If missing: CRITICAL - CLAUDE.md not configured
-- If missing OMC marker: WARN - outdated CLAUDE.md
-
-### Step 5: Check for Stale Plugin Cache
+When users report "OMCO agent not showing in Tab menu" or similar issues, guide them to run:
 
 ```bash
-# Count versions in cache
-ls ~/.claude/plugins/cache/omc/oh-my-claudecode/ 2>/dev/null | wc -l
+npx oh-my-claudecode-opencode doctor
 ```
 
-**Diagnosis**:
-- If > 1 version: WARN - multiple cached versions (cleanup recommended)
-
-### Step 6: Check for Legacy Curl-Installed Content
-
-Check for legacy agents, commands, and skills installed via curl (before plugin system):
-
+Or if npx is not available:
 ```bash
-# Check for legacy agents directory
-ls -la ~/.claude/agents/ 2>/dev/null
-
-# Check for legacy commands directory
-ls -la ~/.claude/commands/ 2>/dev/null
-
-# Check for legacy skills directory
-ls -la ~/.claude/skills/ 2>/dev/null
+cd ~/.config/opencode && node node_modules/oh-my-claudecode-opencode/bin/doctor.js
 ```
 
-**Diagnosis**:
-- If `~/.claude/agents/` exists with oh-my-claudecode-related files: WARN - legacy agents (now provided by plugin)
-- If `~/.claude/commands/` exists with oh-my-claudecode-related files: WARN - legacy commands (now provided by plugin)
-- If `~/.claude/skills/` exists with oh-my-claudecode-related files: WARN - legacy skills (now provided by plugin)
+## 5 Failure Modes
 
-Look for files like:
-- `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
-- `ultrawork.md`, `omc-default.md`, `omc-default-global.md`, `deepsearch.md`, etc. in commands/
-- Any oh-my-claudecode-related `.md` files in skills/
+The doctor tool checks for 5 common failure modes:
 
----
+| # | Check | What It Means |
+|---|-------|---------------|
+| 1 | Plugin Installed | Is the package in `~/.config/opencode/node_modules/`? |
+| 2 | Plugin in Config | Is it registered in `opencode.json` `plugin` array? |
+| 3 | Assets Present | Do `assets/agents/*.md` files exist? |
+| 4 | Package Dependency | Is it listed in `package.json` dependencies? |
+| 5 | OMCO Config Valid | Is `omco.json` valid JSON (if exists)? |
 
-## Report Format
+## Report Analysis
 
-After running all checks, output a report:
+When a user pastes a diagnostic report (JSON or text), analyze it:
 
-```
-## OMC Doctor Report
-
-### Summary
-[HEALTHY / ISSUES FOUND]
-
-### Checks
-
-| Check | Status | Details |
-|-------|--------|---------|
-| Plugin Version | OK/WARN/CRITICAL | ... |
-| Legacy Hooks (settings.json) | OK/CRITICAL | ... |
-| Legacy Scripts (~/.claude/hooks/) | OK/WARN | ... |
-| CLAUDE.md | OK/WARN/CRITICAL | ... |
-| Plugin Cache | OK/WARN | ... |
-| Legacy Agents (~/.claude/agents/) | OK/WARN | ... |
-| Legacy Commands (~/.claude/commands/) | OK/WARN | ... |
-| Legacy Skills (~/.claude/skills/) | OK/WARN | ... |
-
-### Issues Found
-1. [Issue description]
-2. [Issue description]
-
-### Recommended Fixes
-[List fixes based on issues]
-```
+1. **Identify failures**: Look for `FAIL` or `status: "FAIL"` entries
+2. **Check warnings**: Look for `WARN` entries
+3. **Extract recommendations**: The report includes fix commands
 
----
-
-## Auto-Fix (if user confirms)
-
-If issues found, ask user: "Would you like me to fix these issues automatically?"
+## Interpreting Results
 
-If yes, apply fixes:
+### Exit Codes
+- **0**: All checks passed - plugin should work
+- **1**: Critical failure - plugin won't work until fixed
+- **2**: Warnings only - plugin may work but issues exist
 
-### Fix: Legacy Hooks in settings.json
-Remove the `"hooks"` section from `~/.claude/settings.json` (keep other settings intact)
+### Common Fixes
 
-### Fix: Legacy Bash Scripts
+**Plugin Not Installed (FAIL)**
 ```bash
-rm -f ~/.claude/hooks/keyword-detector.sh
-rm -f ~/.claude/hooks/persistent-mode.sh
-rm -f ~/.claude/hooks/session-start.sh
-rm -f ~/.claude/hooks/stop-continuation.sh
+cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest
 ```
 
-### Fix: Outdated Plugin
+**Plugin Not in Config (FAIL)**
 ```bash
-rm -rf ~/.claude/plugins/cache/oh-my-claudecode
-echo "Plugin cache cleared. Restart Claude Code to fetch latest version."
+# Create or edit ~/.config/opencode/opencode.json
+cat > ~/.config/opencode/opencode.json << 'EOF'
+{
+  "plugin": ["oh-my-claudecode-opencode"]
+}
+EOF
 ```
 
-### Fix: Stale Cache (multiple versions)
+**Assets Directory Missing (FAIL)**
 ```bash
-# Keep only latest version
-cd ~/.claude/plugins/cache/omc/oh-my-claudecode/
-ls | sort -V | head -n -1 | xargs rm -rf
+# Reinstall to get fresh assets
+cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest --force
 ```
 
-### Fix: Missing/Outdated CLAUDE.md
-Fetch latest from GitHub and write to `~/.claude/CLAUDE.md`:
-```
-WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md", prompt: "Return the complete raw markdown content exactly as-is")
-```
-
-### Fix: Legacy Curl-Installed Content
-
-Remove legacy agents, commands, and skills directories (now provided by plugin):
-
+**Package Dependency Missing (WARN)**
 ```bash
-# Backup first (optional - ask user)
-# mv ~/.claude/agents ~/.claude/agents.bak
-# mv ~/.claude/commands ~/.claude/commands.bak
-# mv ~/.claude/skills ~/.claude/skills.bak
-
-# Or remove directly
-rm -rf ~/.claude/agents
-rm -rf ~/.claude/commands
-rm -rf ~/.claude/skills
+cd ~/.config/opencode && npm install oh-my-claudecode-opencode --save
 ```
 
-**Note**: Only remove if these contain oh-my-claudecode-related files. If user has custom agents/commands/skills, warn them and ask before removing.
+## After Fixes
 
----
+Always remind users to **restart OpenCode** after making fixes:
+- Close OpenCode (Ctrl+C)
+- Reopen OpenCode
 
-## Post-Fix
+## Reporting Issues
 
-After applying fixes, inform user:
-> Fixes applied. **Restart Claude Code** for changes to take effect.
+If the doctor tool doesn't identify the problem, ask users to:
+1. Share the full doctor report (JSON format preferred)
+2. Share their OpenCode version: `opencode --version`
+3. Open an issue: https://github.com/devswha/oh-my-claudecode-opencode/issues

package/bin/doctor.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+// bin/doctor.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+var OPENCODE_CONFIG_DIR = path.join(os.homedir(), ".config", "opencode");
+var PLUGIN_NAME = "oh-my-claudecode-opencode";
+function checkPluginInstalled() {
+  const pluginPath = path.join(OPENCODE_CONFIG_DIR, "node_modules", PLUGIN_NAME);
+  try {
+    const stats = fs.statSync(pluginPath);
+    if (stats.isDirectory()) {
+      const pkgPath = path.join(pluginPath, "package.json");
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        return {
+          status: "OK",
+          message: `Plugin installed (v${pkg.version})`,
+          details: pluginPath
+        };
+      }
+      return {
+        status: "WARN",
+        message: "Plugin directory exists but package.json missing",
+        details: pluginPath,
+        fix: "Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest"
+      };
+    }
+  } catch (e) {}
+  return {
+    status: "FAIL",
+    message: "Plugin not installed",
+    fix: "Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode"
+  };
+}
+function checkPluginInConfig() {
+  const configPath = path.join(OPENCODE_CONFIG_DIR, "opencode.json");
+  try {
+    if (!fs.existsSync(configPath)) {
+      return {
+        status: "FAIL",
+        message: "opencode.json not found",
+        fix: `Create ${configPath} with: { "plugin": ["oh-my-claudecode-opencode"] }`
+      };
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    const plugins = config.plugin || config.plugins || [];
+    if (Array.isArray(plugins) && plugins.includes(PLUGIN_NAME)) {
+      return {
+        status: "OK",
+        message: "Plugin registered in opencode.json",
+        details: `plugins: ${JSON.stringify(plugins)}`
+      };
+    }
+    return {
+      status: "FAIL",
+      message: "Plugin not in opencode.json plugin array",
+      details: `Current plugins: ${JSON.stringify(plugins)}`,
+      fix: `Add "${PLUGIN_NAME}" to the "plugin" array in opencode.json`
+    };
+  } catch (e) {
+    return {
+      status: "FAIL",
+      message: `Failed to parse opencode.json: ${e.message}`,
+      fix: "Check opencode.json for JSON syntax errors"
+    };
+  }
+}
+function checkAssetsPresent() {
+  const pluginPath = path.join(OPENCODE_CONFIG_DIR, "node_modules", PLUGIN_NAME);
+  const assetsPath = path.join(pluginPath, "assets", "agents");
+  try {
+    if (!fs.existsSync(assetsPath)) {
+      return {
+        status: "FAIL",
+        message: "Assets directory missing",
+        details: `Expected: ${assetsPath}`,
+        fix: "Reinstall: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest"
+      };
+    }
+    const agentFiles = fs.readdirSync(assetsPath).filter((f) => f.endsWith(".md"));
+    if (agentFiles.length === 0) {
+      return {
+        status: "FAIL",
+        message: "No agent files in assets/agents/",
+        fix: "Reinstall: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest"
+      };
+    }
+    return {
+      status: "OK",
+      message: `Found ${agentFiles.length} agent definitions`,
+      details: agentFiles.slice(0, 5).join(", ") + (agentFiles.length > 5 ? "..." : "")
+    };
+  } catch (e) {
+    return {
+      status: "FAIL",
+      message: `Failed to check assets: ${e.message}`,
+      fix: "Check filesystem permissions"
+    };
+  }
+}
+function checkPackageDependency() {
+  const pkgPath = path.join(OPENCODE_CONFIG_DIR, "package.json");
+  try {
+    if (!fs.existsSync(pkgPath)) {
+      return {
+        status: "WARN",
+        message: "No package.json in ~/.config/opencode/",
+        details: "Plugin may have been installed globally or manually",
+        fix: "Initialize: cd ~/.config/opencode && npm init -y && npm install oh-my-claudecode-opencode"
+      };
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps[PLUGIN_NAME]) {
+      return {
+        status: "OK",
+        message: `Listed in package.json: ${deps[PLUGIN_NAME]}`,
+        details: pkgPath
+      };
+    }
+    return {
+      status: "WARN",
+      message: "Plugin not in package.json dependencies",
+      details: "Plugin may work but won't survive npm prune",
+      fix: "Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode --save"
+    };
+  } catch (e) {
+    return {
+      status: "WARN",
+      message: `Failed to parse package.json: ${e.message}`,
+      fix: "Check package.json for JSON syntax errors"
+    };
+  }
+}
+function checkOmcoConfig() {
+  const localConfig = path.join(process.cwd(), ".opencode", "omco.json");
+  const globalConfig = path.join(OPENCODE_CONFIG_DIR, "omco.json");
+  const configPaths = [localConfig, globalConfig];
+  for (const configPath of configPaths) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        return {
+          status: "OK",
+          message: "OMCO config found and valid",
+          details: configPath
+        };
+      } catch (e) {
+        return {
+          status: "FAIL",
+          message: `Invalid JSON in omco.json`,
+          details: configPath,
+          fix: "Fix JSON syntax errors in omco.json"
+        };
+      }
+    }
+  }
+  return {
+    status: "OK",
+    message: "No omco.json (using defaults)",
+    details: "Optional: create .opencode/omco.json for custom config"
+  };
+}
+function runDiagnostics() {
+  const checks = {
+    pluginInstalled: checkPluginInstalled(),
+    pluginInConfig: checkPluginInConfig(),
+    assetsPresent: checkAssetsPresent(),
+    packageDependency: checkPackageDependency(),
+    omcoConfigValid: checkOmcoConfig()
+  };
+  const values = Object.values(checks);
+  const summary = {
+    total: values.length,
+    ok: values.filter((c) => c.status === "OK").length,
+    warn: values.filter((c) => c.status === "WARN").length,
+    fail: values.filter((c) => c.status === "FAIL").length
+  };
+  const recommendations = [];
+  for (const check of values) {
+    if (check.fix && check.status !== "OK") {
+      recommendations.push(check.fix);
+    }
+  }
+  let omcoVersion = null;
+  const pluginPkgPath = path.join(OPENCODE_CONFIG_DIR, "node_modules", PLUGIN_NAME, "package.json");
+  if (fs.existsSync(pluginPkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pluginPkgPath, "utf-8"));
+      omcoVersion = pkg.version;
+    } catch {}
+  }
+  return {
+    timestamp: new Date().toISOString(),
+    omcoVersion,
+    nodeVersion: process.version,
+    platform: process.platform,
+    installPath: path.join(OPENCODE_CONFIG_DIR, "node_modules", PLUGIN_NAME),
+    checks,
+    summary,
+    recommendations
+  };
+}
+function formatTextReport(report) {
+  const lines = [];
+  lines.push("═══════════════════════════════════════════════════════════════");
+  lines.push("                    OMCO Doctor Report                         ");
+  lines.push("═══════════════════════════════════════════════════════════════");
+  lines.push("");
+  lines.push(`Timestamp:    ${report.timestamp}`);
+  lines.push(`OMCO Version: ${report.omcoVersion || "NOT INSTALLED"}`);
+  lines.push(`Node Version: ${report.nodeVersion}`);
+  lines.push(`Platform:     ${report.platform}`);
+  lines.push("");
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("                    Diagnostic Checks                          ");
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push("");
+  const statusIcon = (s) => s === "OK" ? "✓" : s === "WARN" ? "⚠" : "✗";
+  for (const [name, check] of Object.entries(report.checks)) {
+    const icon = statusIcon(check.status);
+    lines.push(`[${icon}] ${check.status.padEnd(4)} | ${name}`);
+    lines.push(`         ${check.message}`);
+    if (check.details) {
+      lines.push(`         Details: ${check.details}`);
+    }
+    lines.push("");
+  }
+  lines.push("───────────────────────────────────────────────────────────────");
+  lines.push(`Summary: ${report.summary.ok} OK, ${report.summary.warn} WARN, ${report.summary.fail} FAIL`);
+  lines.push("───────────────────────────────────────────────────────────────");
+  if (report.recommendations.length > 0) {
+    lines.push("");
+    lines.push("Recommended Fixes:");
+    for (let i = 0;i < report.recommendations.length; i++) {
+      lines.push(`  ${i + 1}. ${report.recommendations[i]}`);
+    }
+  }
+  lines.push("");
+  lines.push("═══════════════════════════════════════════════════════════════");
+  return lines.join(`
+`);
+}
+var args = process.argv.slice(2);
+var jsonOutput = args.includes("--json");
+var outputIndex = args.indexOf("--output");
+var outputFile = outputIndex !== -1 ? args[outputIndex + 1] : null;
+var report = runDiagnostics();
+var output = jsonOutput ? JSON.stringify(report, null, 2) : formatTextReport(report);
+if (outputFile) {
+  fs.writeFileSync(outputFile, output);
+  console.log(`Report saved to: ${outputFile}`);
+} else {
+  console.log(output);
+}
+if (report.summary.fail > 0) {
+  process.exit(1);
+} else if (report.summary.warn > 0) {
+  process.exit(2);
+} else {
+  process.exit(0);
+}

package/bin/doctor.ts

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// bin/doctor.ts - Compiled to bin/doctor.js
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+const OPENCODE_CONFIG_DIR = path.join(os.homedir(), '.config', 'opencode');
+const PLUGIN_NAME = 'oh-my-claudecode-opencode';
+
+interface CheckResult {
+  status: 'OK' | 'WARN' | 'FAIL';
+  message: string;
+  details?: string;
+  fix?: string;
+}
+
+interface DiagnosticReport {
+  timestamp: string;
+  omcoVersion: string | null;
+  nodeVersion: string;
+  platform: string;
+  installPath: string | null;
+  checks: {
+    pluginInstalled: CheckResult;
+    pluginInConfig: CheckResult;
+    assetsPresent: CheckResult;
+    packageDependency: CheckResult;
+    omcoConfigValid: CheckResult;
+  };
+  summary: {
+    total: number;
+    ok: number;
+    warn: number;
+    fail: number;
+  };
+  recommendations: string[];
+}
+
+// ============================================================
+// CHECK 1: Plugin Installation
+// ============================================================
+function checkPluginInstalled(): CheckResult {
+  const pluginPath = path.join(OPENCODE_CONFIG_DIR, 'node_modules', PLUGIN_NAME);
+
+  try {
+    const stats = fs.statSync(pluginPath);
+    if (stats.isDirectory()) {
+      // Read version from package.json
+      const pkgPath = path.join(pluginPath, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return {
+          status: 'OK',
+          message: `Plugin installed (v${pkg.version})`,
+          details: pluginPath
+        };
+      }
+      return {
+        status: 'WARN',
+        message: 'Plugin directory exists but package.json missing',
+        details: pluginPath,
+        fix: 'Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest'
+      };
+    }
+  } catch (e) {
+    // Directory doesn't exist
+  }
+
+  return {
+    status: 'FAIL',
+    message: 'Plugin not installed',
+    fix: 'Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode'
+  };
+}
+
+// ============================================================
+// CHECK 2: Plugin in opencode.json
+// ============================================================
+function checkPluginInConfig(): CheckResult {
+  const configPath = path.join(OPENCODE_CONFIG_DIR, 'opencode.json');
+
+  try {
+    if (!fs.existsSync(configPath)) {
+      return {
+        status: 'FAIL',
+        message: 'opencode.json not found',
+        fix: `Create ${configPath} with: { "plugin": ["oh-my-claudecode-opencode"] }`
+      };
+    }
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const plugins = config.plugin || config.plugins || [];
+
+    if (Array.isArray(plugins) && plugins.includes(PLUGIN_NAME)) {
+      return {
+        status: 'OK',
+        message: 'Plugin registered in opencode.json',
+        details: `plugins: ${JSON.stringify(plugins)}`
+      };
+    }
+
+    return {
+      status: 'FAIL',
+      message: 'Plugin not in opencode.json plugin array',
+      details: `Current plugins: ${JSON.stringify(plugins)}`,
+      fix: `Add "${PLUGIN_NAME}" to the "plugin" array in opencode.json`
+    };
+  } catch (e) {
+    return {
+      status: 'FAIL',
+      message: `Failed to parse opencode.json: ${(e as Error).message}`,
+      fix: 'Check opencode.json for JSON syntax errors'
+    };
+  }
+}
+
+// ============================================================
+// CHECK 3: Assets Directory Present
+// ============================================================
+function checkAssetsPresent(): CheckResult {
+  const pluginPath = path.join(OPENCODE_CONFIG_DIR, 'node_modules', PLUGIN_NAME);
+  const assetsPath = path.join(pluginPath, 'assets', 'agents');
+
+  try {
+    if (!fs.existsSync(assetsPath)) {
+      return {
+        status: 'FAIL',
+        message: 'Assets directory missing',
+        details: `Expected: ${assetsPath}`,
+        fix: 'Reinstall: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest'
+      };
+    }
+
+    const agentFiles = fs.readdirSync(assetsPath).filter(f => f.endsWith('.md'));
+    if (agentFiles.length === 0) {
+      return {
+        status: 'FAIL',
+        message: 'No agent files in assets/agents/',
+        fix: 'Reinstall: cd ~/.config/opencode && npm install oh-my-claudecode-opencode@latest'
+      };
+    }
+
+    return {
+      status: 'OK',
+      message: `Found ${agentFiles.length} agent definitions`,
+      details: agentFiles.slice(0, 5).join(', ') + (agentFiles.length > 5 ? '...' : '')
+    };
+  } catch (e) {
+    return {
+      status: 'FAIL',
+      message: `Failed to check assets: ${(e as Error).message}`,
+      fix: 'Check filesystem permissions'
+    };
+  }
+}
+
+// ============================================================
+// CHECK 4: package.json Dependency
+// ============================================================
+function checkPackageDependency(): CheckResult {
+  const pkgPath = path.join(OPENCODE_CONFIG_DIR, 'package.json');
+
+  try {
+    if (!fs.existsSync(pkgPath)) {
+      return {
+        status: 'WARN',
+        message: 'No package.json in ~/.config/opencode/',
+        details: 'Plugin may have been installed globally or manually',
+        fix: 'Initialize: cd ~/.config/opencode && npm init -y && npm install oh-my-claudecode-opencode'
+      };
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (deps[PLUGIN_NAME]) {
+      return {
+        status: 'OK',
+        message: `Listed in package.json: ${deps[PLUGIN_NAME]}`,
+        details: pkgPath
+      };
+    }
+
+    return {
+      status: 'WARN',
+      message: 'Plugin not in package.json dependencies',
+      details: 'Plugin may work but won\'t survive npm prune',
+      fix: 'Run: cd ~/.config/opencode && npm install oh-my-claudecode-opencode --save'
+    };
+  } catch (e) {
+    return {
+      status: 'WARN',
+      message: `Failed to parse package.json: ${(e as Error).message}`,
+      fix: 'Check package.json for JSON syntax errors'
+    };
+  }
+}
+
+// ============================================================
+// CHECK 5: OMCO Config Valid
+// ============================================================
+function checkOmcoConfig(): CheckResult {
+  const localConfig = path.join(process.cwd(), '.opencode', 'omco.json');
+  const globalConfig = path.join(OPENCODE_CONFIG_DIR, 'omco.json');
+
+  const configPaths = [localConfig, globalConfig];
+
+  for (const configPath of configPaths) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        return {
+          status: 'OK',
+          message: 'OMCO config found and valid',
+          details: configPath
+        };
+      } catch (e) {
+        return {
+          status: 'FAIL',
+          message: `Invalid JSON in omco.json`,
+          details: configPath,
+          fix: 'Fix JSON syntax errors in omco.json'
+        };
+      }
+    }
+  }
+
+  // No config found - this is optional
+  return {
+    status: 'OK',
+    message: 'No omco.json (using defaults)',
+    details: 'Optional: create .opencode/omco.json for custom config'
+  };
+}
+
+// ============================================================
+// MAIN
+// ============================================================
+function runDiagnostics(): DiagnosticReport {
+  const checks = {
+    pluginInstalled: checkPluginInstalled(),
+    pluginInConfig: checkPluginInConfig(),
+    assetsPresent: checkAssetsPresent(),
+    packageDependency: checkPackageDependency(),
+    omcoConfigValid: checkOmcoConfig(),
+  };
+
+  const values = Object.values(checks);
+  const summary = {
+    total: values.length,
+    ok: values.filter(c => c.status === 'OK').length,
+    warn: values.filter(c => c.status === 'WARN').length,
+    fail: values.filter(c => c.status === 'FAIL').length,
+  };
+
+  const recommendations: string[] = [];
+  for (const check of values) {
+    if (check.fix && check.status !== 'OK') {
+      recommendations.push(check.fix);
+    }
+  }
+
+  // Get installed version
+  let omcoVersion: string | null = null;
+  const pluginPkgPath = path.join(OPENCODE_CONFIG_DIR, 'node_modules', PLUGIN_NAME, 'package.json');
+  if (fs.existsSync(pluginPkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf-8'));
+      omcoVersion = pkg.version;
+    } catch {}
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    omcoVersion,
+    nodeVersion: process.version,
+    platform: process.platform,
+    installPath: path.join(OPENCODE_CONFIG_DIR, 'node_modules', PLUGIN_NAME),
+    checks,
+    summary,
+    recommendations,
+  };
+}
+
+function formatTextReport(report: DiagnosticReport): string {
+  const lines: string[] = [];
+
+  lines.push('═══════════════════════════════════════════════════════════════');
+  lines.push('                    OMCO Doctor Report                         ');
+  lines.push('═══════════════════════════════════════════════════════════════');
+  lines.push('');
+  lines.push(`Timestamp:    ${report.timestamp}`);
+  lines.push(`OMCO Version: ${report.omcoVersion || 'NOT INSTALLED'}`);
+  lines.push(`Node Version: ${report.nodeVersion}`);
+  lines.push(`Platform:     ${report.platform}`);
+  lines.push('');
+  lines.push('───────────────────────────────────────────────────────────────');
+  lines.push('                    Diagnostic Checks                          ');
+  lines.push('───────────────────────────────────────────────────────────────');
+  lines.push('');
+
+  const statusIcon = (s: string) => s === 'OK' ? '✓' : s === 'WARN' ? '⚠' : '✗';
+
+  for (const [name, check] of Object.entries(report.checks)) {
+    const icon = statusIcon(check.status);
+    lines.push(`[${icon}] ${check.status.padEnd(4)} | ${name}`);
+    lines.push(`         ${check.message}`);
+    if (check.details) {
+      lines.push(`         Details: ${check.details}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('───────────────────────────────────────────────────────────────');
+  lines.push(`Summary: ${report.summary.ok} OK, ${report.summary.warn} WARN, ${report.summary.fail} FAIL`);
+  lines.push('───────────────────────────────────────────────────────────────');
+
+  if (report.recommendations.length > 0) {
+    lines.push('');
+    lines.push('Recommended Fixes:');
+    for (let i = 0; i < report.recommendations.length; i++) {
+      lines.push(`  ${i + 1}. ${report.recommendations[i]}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('═══════════════════════════════════════════════════════════════');
+
+  return lines.join('\n');
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const jsonOutput = args.includes('--json');
+const outputIndex = args.indexOf('--output');
+const outputFile = outputIndex !== -1 ? args[outputIndex + 1] : null;
+
+const report = runDiagnostics();
+
+// Output
+const output = jsonOutput ? JSON.stringify(report, null, 2) : formatTextReport(report);
+
+if (outputFile) {
+  fs.writeFileSync(outputFile, output);
+  console.log(`Report saved to: ${outputFile}`);
+} else {
+  console.log(output);
+}
+
+// Exit code: 0=OK, 1=FAIL, 2=WARN
+if (report.summary.fail > 0) {
+  process.exit(1);
+} else if (report.summary.warn > 0) {
+  process.exit(2);
+} else {
+  process.exit(0);
+}

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "oh-my-claudecode-opencode",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OpenCode port of oh-my-claudecode - Multi-agent orchestration plugin (omco)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "bin": {
+    "omco-doctor": "./bin/doctor.js",
+    "oh-my-claudecode-opencode": "./bin/doctor.js"
+  },
   "files": [
     "dist",
-    "assets"
+    "assets",
+    "bin"
   ],
   "exports": {
     ".": {
@@ -17,7 +22,7 @@
     "./schema.json": "./assets/omco.schema.json"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly",
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm && bun build bin/doctor.ts --outfile bin/doctor.js --target node --format esm && tsc --emitDeclarationOnly",
     "build:watch": "bun build src/index.ts --outdir dist --target bun --format esm --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run clean && bun run build",