Skip to main content

moai doctor Diagnostics

UPDATED 2026-09-10 1 min read EDIT ON GITHUB ↗

moai doctor runs comprehensive system diagnostics. It checks Claude Code configuration, dependencies, project structure, language-specific development tools, and the environment, and can suggest fixes for detected issues.

Overview

bash
moai doctor [OPTIONS]

Flags

FlagDescription
-v, --verboseShow detailed diagnostic information (tool versions, language detection)
--fixSuggest fixes for detected issues
--exportExport diagnostics to a JSON file
--check <tool>Run a specific check only (e.g. git, go, config)

Subcommands

moai doctor provides subcommands that dive deeper into a specific area.

CommandDescription
moai doctor configConfiguration diagnostics — inspect merged settings with provenance
moai doctor hookShow the 27-event hook coverage table
moai doctor permissionDiagnose permission resolution
moai doctor sandboxSandbox backend availability diagnostics

moai doctor config in turn offers dump (dump merged settings) and diff <tier-a> <tier-b> (compare two settings tiers).

A full moai doctor run carries a Home Disk Usage entry. It reports how full the ~/.moai home directory is and is advisory: exceeding the threshold never blocks another command.

Reported itemContent
Total sizeThe total ~/.moai footprint plus its three largest entries
Per-profile breakdownThe size of each claude-profiles/<profile> with its category split
Release countHow many binaries remain in releases/, and the current version
Cleanable bytesThe estimate of what moai clean --home could actually delete
~/.claudeSize only — never a cleanup target on any path

When the cleanable estimate exceeds the threshold (a compiled default of 500 MB) the status turns WARN and recommends moai clean --home (dry-run by default). Below it, the status stays OK. When no ~/.moai exists at all, the check reports “nothing to report” and passes.

The estimate calls the same scanner moai clean --home uses, so the number doctor quotes and the list clean actually deletes cannot drift apart. Full detail: Home Directory Hygiene.

moai update can pass over hook entries the template newly ships without ever landing them in an existing project’s .claude/settings.json. The Hook Delivery check finds those gaps: within the hook event keys the project already carries, it compares the shipped template against the project file and reports entries the template carries but the project lacks.

Reported itemContent
Missing entriesNamed as hooks.PreToolUse missing handle-pre-tool.sh (matcher AskUserQuestion) — the event key and matcher included
How to fixRe-add each missing entry under the named event key, copying the block from the template settings of your moai version
Post-update verificationThe command that shows whether moai update deleted managed files (git status --porcelain | grep '^ D') — on a hit, restore with git restore -- <path> before re-adding the entries

The check is read-only — it never writes .claude/settings.json. Event keys the template introduces for the first time and entries you authored yourself are never counted as missing, and opted-out entries are not expected either (the template renders with your project’s own hook.opt_in.enabled setting). When everything matches, the check reports ok.

A full moai doctor run carries a Codex Wiring entry. It examines whether the project’s Codex wiring — the generated hooks, the MCP registration, and the skill mirror — is intact. The check is advisory, fail-open, and read-only: it reports what it finds and never repairs anything itself.

Check itemContent
.codex/hooks.json presence · key whitelistWhether the wiring file exists and its keys match the whitelist. One stray key makes codex silently ignore the whole file, so this check observes that silence in its place
Sidecar hashCompares the current file against the hook-content hash recorded at deploy time, catching the divergence left behind after hooks were hand-edited
moai binary PATHGenerated hook commands are moai hook ..., so nothing fires if moai cannot be found on PATH
[mcp_servers.moai] in .codex/config.tomlWhether the MCP registration table exists and matches the standard registration shape. The table is user-owned, so doctor reports it and never repairs it
.agents/skills skill mirrorCodex CLI does not scan .claude/skills, so without the mirror — or with a broken link — codex sees none of this project’s MoAI skills
User-layer [[skills.config]] registrationsInspects the skill registrations in ~/.codex/config.toml ($CODEX_HOME/config.toml when set) for path and enabled key shape. This item is checked only when codex is in play — that is, when the project is wired or codex is installed

When the check finds a problem, the fix directive baked into the code is shown alongside.

FindingDirective
Project with no wiring at allmoai init --llm codex
Sidecar divergence after hook changesRe-trust the changed hooks with codex /hooks
Missing skill mirror · broken linkmoai update --templates-only --force --yes
Registration whose skill file has vanishedRemove the entry or restore the skill file

Exactly one of the findings this check can produce is classified fatal: if a user-layer [[skills.config]] entry lacks the enabled key or carries a value that is not a bare TOML boolean, codex exits 1 on every invocation. Hitting this single fatal finding turns the doctor result into Fail and carries the exit code 1. This behavior was observed on codex-cli 0.153.4 — it is confirmed for that release only and is not generalized to other releases. The correct shape is to state enabled = true or enabled = false explicitly on every entry. Every finding other than this one is advisory and does not change doctor’s exit code.

On a machine without codex, a claude-only project carrying no wiring makes this check skip silently — an informational skip that produces no warning row. For reference, bulk-collecting ghost registrations that point at skill files that no longer exist sits outside this check’s directives; it is a separate verb, moai clean --codex-skills.

Codex wiring overall — the hook trust model and the skill mirror included — is covered in detail in Codex Dual Harness.

Exit codes

Scripts and CI wrappers calling moai doctor read the exit code, not the summary line.

Exit codeMeaning
0No failing check. Warnings are advisory and do not change the exit code
1One or more checks failed — the summary’s Fail N carried through

The Constitution Registry check does more than confirm the registry parses: it runs the same drift validation as moai constitution validate. Doctor therefore cannot report ok on a checkout where validate fails. Bypassing with MOAI_CONSTITUTION_SKIP_VALIDATE=1 returns doctor to its structural verdict.

Examples

bash
# Full diagnostics
moai doctor

# Detailed diagnostics
moai doctor --verbose

# Export diagnostics
moai doctor --export diagnostics.json

# Diagnose a specific area
moai doctor hook          # hook coverage table
moai doctor permission    # permission resolution
moai doctor sandbox       # sandbox backend

Related: Project Status · CLI Overview