CtrlK
BlogDocsLog inGet started
Tessl Logo

omc-doctor

Diagnose and fix oh-my-claudecode installation issues

66

Quality

58%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/omc-doctor/SKILL.md
SKILL.md
Quality
Evals
Security

Doctor Skill

Note: All ~/.claude/... paths in this guide respect CLAUDE_CONFIG_DIR when that environment variable is set.

Task: Run Installation Diagnostics

You are the OMC Doctor - diagnose and fix installation issues.

Step 1: Check Plugin Version

# Get installed and latest versions (cross-platform)
node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),d=process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));console.log('Installed:',v.length?v[v.length-1]:'(none)')}catch{console.log('Installed: (none)')}"
npm view oh-my-claudecode version 2>/dev/null || echo "Latest: (unavailable)"

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 both ~/.claude/settings.json (profile-level) and ./.claude/settings.json (project-level) 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

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

# Check if CLAUDE.md exists
ls -la ~/.claude/CLAUDE.md 2>/dev/null

# Check for OMC markers (<!-- OMC:START --> is the canonical marker)
grep -q "<!-- OMC:START -->" ~/.claude/CLAUDE.md 2>/dev/null && echo "Has OMC config" || echo "Missing OMC config in CLAUDE.md"

# Check companion files for file-split pattern (e.g. CLAUDE-omc.md)
find "$HOME/.claude" -maxdepth 1 -type f -name 'CLAUDE-*.md' -print 2>/dev/null
while IFS= read -r f; do
  grep -q "<!-- OMC:START -->" "$f" 2>/dev/null && echo "Has OMC config in companion: $f"
done < <(find "$HOME/.claude" -maxdepth 1 -type f -name 'CLAUDE-*.md' -print 2>/dev/null)

# Check if CLAUDE.md references a companion file
grep -o "CLAUDE-[^ )]*\.md" ~/.claude/CLAUDE.md 2>/dev/null

Diagnosis:

  • If CLAUDE.md missing: CRITICAL - CLAUDE.md not configured
  • If <!-- OMC:START --> found in CLAUDE.md: OK
  • If <!-- OMC:START --> found in a companion file (e.g. CLAUDE-omc.md): OK - file-split pattern detected
  • If no OMC markers in CLAUDE.md or any companion file: WARN - outdated CLAUDE.md

Step 5: Check for Stale Plugin Cache

# Count versions in cache (cross-platform)
node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),d=process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x));console.log(v.length+' version(s):',v.join(', '))}catch{console.log('0 versions')}"

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). Important: Only flag files whose names match actual plugin-provided names. Do NOT flag user's custom agents/commands/skills that are unrelated to OMC.

# 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

Diagnosis:

  • If ~/.claude/agents/ exists with files matching plugin agent names: WARN - legacy agents (now provided by plugin)
  • If ~/.claude/commands/ exists with files matching plugin command names: WARN - legacy commands (now provided by plugin)
  • If ~/.claude/skills/ exists with files matching plugin skill names: WARN - legacy skills (now provided by plugin)
  • If custom files exist that do NOT match plugin names: OK - these are user custom content, do not flag them

Known plugin agent names (check agents/ for these): architect.md, document-specialist.md, explore.md, executor.md, debugger.md, planner.md, analyst.md, critic.md, verifier.md, test-engineer.md, designer.md, writer.md, qa-tester.md, scientist.md, security-reviewer.md, code-reviewer.md, git-master.md, code-simplifier.md

Known plugin skill names (check skills/ for these): ai-slop-cleaner, ask, autopilot, cancel, ccg, configure-notifications, deep-interview, deepinit, external-context, hud, learner, mcp-setup, omc-doctor, omc-setup, omc-teams, plan, project-session-manager, ralph, ralplan, release, sciomc, setup, skill, team, ultraqa, ultrawork, writer-memory

Known plugin command names (check commands/ for these): ultrawork.md, deepsearch.md

Report Format

After running all checks, output a report:

## 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]

Auto-Fix (if user confirms)

If issues found, ask user: "Would you like me to fix these issues automatically?"

If yes, apply fixes:

Fix: Legacy Hooks in settings.json

Remove the "hooks" section from ~/.claude/settings.json (keep other settings intact)

Fix: Legacy Bash Scripts

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

Fix: Outdated Plugin

# Clear plugin cache (cross-platform)
node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{f.rmSync(b,{recursive:true,force:true});console.log('Plugin cache cleared. Restart Claude Code to fetch latest version.')}catch{console.log('No plugin cache found')}"

Fix: Stale Cache (multiple versions)

# Keep only latest version (cross-platform)
node -e "const p=require('path'),f=require('fs'),h=require('os').homedir(),d=process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude'),b=p.join(d,'plugins','cache','omc','oh-my-claudecode');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));v.slice(0,-1).forEach(x=>f.rmSync(p.join(b,x),{recursive:true,force:true}));console.log('Removed',v.length-1,'old version(s)')}catch(e){console.log('No cache to clean')}"

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):

# 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

Note: Only remove if these contain oh-my-claudecode-related files. If user has custom agents/commands/skills, warn them and ask before removing.

Post-Fix

After applying fixes, inform user:

Fixes applied. Restart Claude Code for changes to take effect.

Repository
Yeachan-Heo/oh-my-claudecode
Commit

48ffaac

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill