Doctor

Doctor Skill

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

Canonical skill root

OMX installs skills to ${CODEX_HOME:-~/.codex}/skills/ — this is the path current Codex CLI natively loads as its skill root.

~/.agents/skills/ is a historical legacy path from an older Codex CLI release, before Codex settled on ~/.codex as its home directory. Current Codex CLI and OMX no longer write there.

In a mixed OMX + plain Codex environment:

• Use: ${CODEX_HOME:-~/.codex}/skills/ (user scope) or .codex/skills/ (project scope)
• Clean up if present: ~/.agents/skills/ — if this still exists alongside the canonical root, Codex's Enable/Disable Skills UI will show duplicate entries for any skill present in both trees
• Interop rule: OMX writes only to the canonical path; archive or remove ~/.agents/skills/ once you have confirmed ${CODEX_HOME:-~/.codex}/skills/ is your active root

Task: Run Installation Diagnostics

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

Step 1: Check Plugin Version

Official Codex plugin caches are marketplace- and version-scoped, for example ${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/. Local installs may use local as the version identifier.

# Get installed plugin cache versions across marketplaces.
# Cache shape: $PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex/$PLUGIN_VERSION/
PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
CACHE_ENTRIES=$(find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null)

if [[ -z "$CACHE_ENTRIES" ]]; then
  echo "Installed plugin cache: none"
else
  while IFS= read -r VERSION_DIR; do
    MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
    PLUGIN_VERSION=$(basename "$VERSION_DIR")
    printf 'Installed plugin cache: marketplace=%s version=%s path=%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION" "$VERSION_DIR"
  done <<< "$CACHE_ENTRIES"
fi

# Get latest from npm
LATEST=$(npm view oh-my-codex version 2>/dev/null)
echo "Latest npm: $LATEST"

Diagnosis:

• If no cache entry exists: INFO - plugin marketplace artifact not cached; this may be normal when OMX was installed only through npm/setup
• Compare each printed PLUGIN_VERSION with LATEST; if it differs and is not local: WARN - outdated plugin cache
• If one marketplace has multiple version directories: WARN - stale cache for that marketplace/plugin pair
• Remember: plugin install/discovery is not a replacement for npm install -g oh-my-codex plus omx setup; the packaged plugin carries plugin-scoped companion metadata for optional MCP compatibility servers and apps, with first-party MCP disabled by default, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned

Step 2: Check Hook Configuration (config.toml + legacy settings.json)

Check ~/.codex/config.toml first (current Codex config), then check legacy ~/.codex/settings.json only if it exists.

Look for hook entries pointing to removed scripts like:

• bash $HOME/.codex/hooks/keyword-detector.sh
• bash $HOME/.codex/hooks/persistent-mode.sh
• bash $HOME/.codex/hooks/session-start.sh

Diagnosis:

• If found: CRITICAL - legacy hooks causing duplicates

Step 3: Check for Legacy Bash Hook Scripts

ls -la ~/.codex/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 AGENTS.md

# Check if AGENTS.md exists
ls -la ~/.codex/AGENTS.md 2>/dev/null

# Check for OMX marker
grep -q "oh-my-codex Multi-Agent System" ~/.codex/AGENTS.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"

Diagnosis:

• If missing: CRITICAL - AGENTS.md not configured
• If missing OMX marker: WARN - outdated AGENTS.md

Step 5: Check for Stale Plugin Cache

# List marketplace/version cache entries for this plugin
PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null \
  | while IFS= read -r VERSION_DIR; do
      MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
      PLUGIN_VERSION=$(basename "$VERSION_DIR")
      printf '%s\t%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION"
    done

Diagnosis:

• If a single marketplace lists multiple versions: WARN - multiple cached versions for that marketplace/plugin pair (cleanup recommended)