- Installs
- 140
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/yeachan-heo/oh-my-codex --skill doctor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads doctor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
OMX Doctor
Use this task card to diagnose installation/discovery problems. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in templates/AGENTS.md. ~/.codex means ${CODEX_HOME:-~/.codex} when CODEX_HOME is set.
Run diagnostics
omx doctor
omx doctor --team # include Team runtime checks
omx doctor --verbose # include detailed check evidence
omx doctor --force # repair eligible repo artifact ownership issues
omx doctor --dry-run --force # preview eligible ownership repairs
For a local source checkout, build first and invoke node dist/cli/omx.js doctor. Keep command output and exact paths for the report.
Plugin cache and 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 d; do
m=$(basename "$(dirname "$(dirname "$d")")"); v=$(basename "$d")
printf 'Installed plugin cache: marketplace=%s version=%s path=%s\n' "$m" "$v" "$d"
done <<<"$CACHE_ENTRIES"
fi
LATEST=$(npm view oh-my-codex version 2>/dev/null)
echo "Latest npm: $LATEST"
No cache is INFO (normal for npm/setup-only installs). A non-local cache version differing from LATEST, or multiple versions for one marketplace, is WARN. Plugin discovery does not replace npm installation plus omx setup; native/runtime wiring remains setup-owned.
Hooks, AGENTS, and skill roots
CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
ls -la "$CODEX_DIR/config.toml" "$CODEX_DIR/settings.json" 2>/dev/null
rg 'keyword-detector|persistent-mode|session-start|stop-continuation' "$CODEX_DIR/config.toml" "$CODEX_DIR/settings.json" 2>/dev/null || true
ls -la "$CODEX_DIR/hooks"/*.sh 2>/dev/null
ls -la "$CODEX_DIR/AGENTS.md" 2>/dev/null
grep -q "oh-my-codex Multi-Agent System" "$CODEX_DIR/AGENTS.md" 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"
ls -la "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$CODEX_DIR/skills" "$HOME/.agents/skills" 2>/dev/null
Classify legacy hook references as CRITICAL (duplicate hooks). The scripts keyword-detector.sh, persistent-mode.sh, session-start.sh, and stop-continuation.sh are WARN. Missing AGENTS.md is CRITICAL; missing the OMX marker is WARN. ${CODEX_HOME:-~/.codex}/skills is the canonical user root. ~/.agents/skills is historical and overlapping trees can duplicate skill entries. OMX files under legacy agents/ or commands/ are WARN.
With --team, retain any resume_blocker, slow_shutdown, delayed_status_lag, stale_leader, or orphan_tmux_session diagnostics; failed checks set a non-zero exit status.
Report contract
## OMX Doctor Report
### Summary
[HEALTHY / ISSUES FOUND]
### Checks
| Check | Status | Details |
| Plugin Version | OK/WARN/INFO | ... |
| Hook Config (config.toml / legacy settings.json) | OK/CRITICAL | ... |
| Legacy Scripts (~/.codex/hooks/) | OK/WARN | ... |
| AGENTS.md | OK/WARN/CRITICAL | ... |
| Plugin Cache | OK/WARN | ... |
| Legacy Agents / Commands | OK/WARN | ... |
| Skills (canonical / historical root) | OK/WARN | ... |
### Issues Found
1. ...
### Recommended Fixes
...
Remediation (after user confirmation and confirming each target is OMX-owned)
Remove only confirmed OMX legacy content; preserve unrelated user files:
# If settings.json exists, remove only its legacy "hooks" section.
rm -f "$CODEX_DIR/hooks/keyword-detector.sh" "$CODEX_DIR/hooks/persistent-mode.sh" "$CODEX_DIR/hooks/session-start.sh" "$CODEX_DIR/hooks/stop-continuation.sh"
PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex" -type d -prune -exec rm -rf {} +
For older curl installs, inspect first and remove only directories containing OMX-managed files:
ls -la "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$CODEX_DIR/skills" "$HOME/.agents/skills" 2>/dev/null
# Optional backups:
# mv "$CODEX_DIR/agents" "$CODEX_DIR/agents.bak"
# mv "$CODEX_DIR/commands" "$CODEX_DIR/commands.bak"
# mv "$HOME/.agents/skills" "$HOME/.agents/skills.bak"
rm -rf "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$HOME/.agents/skills"
If AGENTS.md is missing/outdated, fetch the current raw file and write it to $CODEX_DIR/AGENTS.md:
WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/AGENTS.md", prompt: "Return the complete raw markdown content exactly as-is")
To keep only the newest cache version for a selected marketplace:
PLUGIN_CACHE_DIR="$PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex"
KEEP_VERSION=$(for d in "$PLUGIN_CACHE_DIR"/*; do [[ -d "$d" ]] && basename "$d"; done | sort -V | tail -1)
[[ -n "$KEEP_VERSION" ]] && find "$PLUGIN_CACHE_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "$KEEP_VERSION" -exec rm -rf {} +
If AGENTS.md is missing or stale, refresh it from the current release source, then rerun omx doctor. If legacy ~/.agents/skills overlaps the canonical root, archive/remove that tree only after checking for custom skills. Restart Codex after fixes and report before/after evidence.
Exit conditions
Stop with HEALTHY only when required paths, hook/config checks, AGENTS marker, plugin cache status, and (when requested) Team checks pass. Otherwise report ISSUES FOUND, exact failed evidence, and the smallest confirmed remediation; do not claim a fix from a recommendation alone.
FAQ
What does the doctor skill do?
Diagnose and fix oh-my-codex installation issues
How do I install doctor?
Run npx skills add https://github.com/yeachan-heo/oh-my-codex --skill doctor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/doctor/ (personal) or .claude/skills/doctor/ (project).
Which AI agents can use doctor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is doctor safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains doctor?
It is published by yeachan-heo in yeachan-heo/oh-my-codex. It has 140 recorded installs.
More from yeachan-heo/oh-my-codex
deep-interview
yeachan-heo/oh-my-codex
Socratic deep interview with mathematical ambiguity gating before execution
ultraqa
yeachan-heo/oh-my-codex
Adversarial dynamic e2e QA workflow - generate hostile scenarios, test, verify, fix, report, and clean up
ralplan
yeachan-heo/oh-my-codex
Consensus planning stage for Planner - Architect - Critic handoff to $ultragoal
ai-slop-cleaner
yeachan-heo/oh-my-codex
Run an anti-slop cleanup/refactor/deslop workflow
team
yeachan-heo/oh-my-codex
N coordinated agents on shared task list using tmux-based orchestration
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.