OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.
Claude Code 2.1.220+ for xhigh effort warning (Category 14); earlier versions skip that check.
description
OrchestKit doctor for health diagnostics across manifest integrity, hook configuration, skill validation, agent frontmatter, MCP server connectivity, CC version compatibility, and permission rules. Reports issues with severity levels and auto-remediation suggestions. Validates component counts, detects orphaned entries, and checks CC version matrix compliance. Use when diagnosing plugin health, troubleshooting configuration issues, or running pre-release checks.
A full doctor run takes ~20s. Most invocations only need one slice. Ask the user up-front so voice-flow shortcuts ("just the MCPs") map cleanly:
# Skip the prompt when an explicit scope arg or env override is present:# /ork:doctor cc → skip, use cc-only# /ork:doctor mcp → skip, use mcp-only# /ork:doctor plugin → skip, use plugin-only# ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value## Otherwise, ask:
AskUserQuestion(questions=[{
"question": "What should doctor check?",
"header": "Scope",
"options": [
{"label": "Everything (default)", "description": "Full system health — ~20s; runs all 15 categories"},
{"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},
{"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},
{"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}
]
}])
Skip the prompt entirely when the scope is unambiguous from the invocation. The fast scopes (3-8s) are 3-7× faster than the full run — voice users say "just the MCPs" and get a 5s answer.
Overview
The /ork:doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 16 categories:
Hook Health - Registration, bundles, async patterns
Permission Rules - Detects unreachable rules
Schema Compliance - Validates JSON files against schemas
Coordination System - Checks lock health and registry integrity
Context Budget - Monitors token usage against budget
Memory System - Graph memory health
Claude Code Version - Validates CC >= 2.1.220 (supported floor). Everything the old "recommends 2.1.154+" note gated (xhigh effort, /ultrareview, stream-json plugin_errors) is floor-guaranteed now, so there is nothing left to recommend
MCP Status - Active vs disabled vs misconfigured, API key presence for paid MCPs. CC 2.1.110: detects duplicate definitions across config scopes. Sub-check warns when HIGH-tier servers resolve to @latest in .mcp.json (closes #1462)
Plugin Validate - Runs claude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)
Effort/Model Compatibility - Warns only when xhigh effort is configured AND the active model is provably unable to run it. Silent otherwise, because the fallback itself is silent
Sandbox Posture - CC Bash-sandbox on/off in settings.local.json, with a /sandbox nudge
Operator Settings Posture - Detects security controls that a plugin bundle cannot carry (credential-read deny rules, the sandbox block, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) and are therefore missing unless the operator wrote them into their own settings
When to Use
After installing or updating OrchestKit
When hooks aren't firing as expected
Before deploying to a team environment
When debugging coordination issues
After running npm run build
Quick Start
/ork:doctor # Standard health check
/ork:doctor -v # Verbose output
/ork:doctor --json # Machine-readable for CI
CLI Options
Flag
Description
-v, --verbose
Detailed output per check
--json
JSON output for CI integration
--category=X
Run only specific category
Health Check Categories
Detailed check procedures: Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/diagnostic-checks.md") for bash commands and validation logic per category.
MCP-specific checks: Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/mcp-status-checks.md") for credential validation and misconfiguration detection.
Output examples: Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/health-check-outputs.md") for sample output per category.
hooks.json schema, bundles, async patterns — across all three hook scopes: global, agent-scoped, and skill-scoped. Detects the common hook problems: missing files (registered but not on disk), syntax errors in hooks.json or bundles, permission issues (non-executable scripts), and stale references (entries pointing at renamed/removed handlers)
Activation-channel orphans (repo / pre-release): a user-invocable skill should be reachable by more than a human typing it — via a chain (another skill references /ork:<skill>), a subagent grant (skills: in src/agents/*.md), or a background trigger. A skill with none is an "island" that silently rots. In a repo checkout, run npm run test:manifests:channels (gated in CI via test:manifests). Fix an island by wiring any one channel, or add it to STANDALONE_ALLOWLIST with a justification.
Categories 4-5: System Health
Category
What It Checks
Reference
4. Memory
.claude/memory/ graph integrity + queue depth; auto-memory MEMORY.md index budget (≤24.4 KB; warns + recommends /ork:dream on re-bloat)
Analytics writer liveness (System Health): the local analytics pipeline has several independent JSONL writers under ~/.claude/analytics/ (skill-usage, agent-usage, hook-timing). A writer can die silently while its siblings stay hot — observed once for four months (skill-usage.jsonl, 2026-03 to 2026-07). The check is a peer comparison: flag any watched file whose last write is ≥48h old while a sibling wrote within 24h (stat -f '%m %N' ~/.claude/analytics/*.jsonl). The lifecycle/analytics-liveness-check SessionStart hook runs the same comparison continuously.
A flagged writer means the write path was dropped from dispatch, so check both surfaces — src/hooks/hooks.json AND the entries map (src/hooks/src/entries/*.ts). A hook present in one but not the other is registered-looking and silently dead: the #959 failure class. /ork:telemetry-inspect gives the per-file deep dive, including the field-level defects tracked in #3034 (constant fields) and #3035 (phantom rows), which this structural check cannot see.
(Category numbering in this file is inconsistent between the Overview list above and these tables — the Overview numbers 4 as Hook Health, the tables number 4 as Memory. This check belongs to System Health regardless of which numbering a reader follows.)
Categories 6-9: Infrastructure
Category
What It Checks
6. Permission Rules
Unreachable rules detection
7. Schema Compliance
JSON files against schemas
8. Coordination
Multi-worktree lock health, stale locks, sparse paths config
Controls a plugin bundle cannot carry, so they exist only if the operator wrote them: credential-read permissions.deny rules (zero hook coverage, measured), the sandbox block incl. network.deniedDomains (the egress guard only asks on the upload shape; a plain GET abstains), and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS (ork's own agent-teams.ts gates on it). Warn-level; prints the JSON to paste
Why Check 16 exists at all:plugins-reference.md:858 says "Only the agent and subagentStatusLine keys are currently supported" in a plugin's bundled settings.json. Everything else ork used to declare there was inert, so the protection it looked like it shipped was never in force. Check 16 is the replacement: detect the gap in a scope CC really reads, then hand the operator the exact JSON. The ork:configure skill, section Operator-Scope Settings, carries the paste-ready blocks.
CC 2.1.111 added the xhigh effort tier. The only reason this category exists is the silence: a model that does not implement xhigh degrades the request to high with no error, no warning, and no log line, so the extra deepening pass the affected skills document is lost without any visible signal. If CC ever surfaces the downgrade itself, delete this category.
The check is capability-shaped, not model-name-shaped. Never hardcode "the current frontier model" here: that guarantees a false failure the day the next one ships, and it prescribes a downgrade to a superseded model.
Do not route this through src/hooks/src/lib/models.vocab.json. That file is the model-id/pricing vocabulary and carries no effort or capability fields at all, so keying off it would leave the check permanently, accidentally dead rather than deliberately quiet.
Detection (warn only on positive proof):
Resolve the configured effort, in order: .claude/settings.json → effort, then $ORCHESTKIT_EFFORT (populated by the effort-detector hook), then any .claude/chain/*.json entry that explicitly set effort: xhigh. No xhigh anywhere means pass, no output.
Resolve the active model id.
Warn only when that model id matches a prefix in doctor's local XHIGH_UNSUPPORTED_PREFIXES table below. Every other outcome (model absent from the table, model id unresolvable, settings file missing) is a pass. A check that cannot prove a problem stays quiet.
# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:# a model absent from this table is assumed to support xhigh and emits nothing.# Add an entry only from an OBSERVED silent degrade, citing the CC version it was# seen on. Never add one by inferring from a model being new, old, or cheap.
XHIGH_UNSUPPORTED_PREFIXES = [
# prefix evidence"claude-3-", # the whole Claude 3 line predates CC 2.1.111, which introduced the tier
]
An empty or short table is the correct resting state. Silence here means "doctor has no proof of a problem", which is a true statement, whereas a name-matched failure against an unrecognized model is a false one.
Warning format (no model name is hardcoded, both sides are read at runtime):
WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.
Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)
Impact: the run degrades to `high` with no error and no log line, so the extra
deepening pass is lost with nothing to notice it by.
Fix: run this on a model that implements `xhigh`, or set effort to `high` so the
config matches what actually executes.
Exit code: Non-zero in --json mode only when the warning actually fires; soft warning in interactive mode. A silent pass is exit 0.
Report Format
Every category reports an explicit pass / warn / fail status, and every warn or fail comes with specific fix steps for that failure type (the exact command to run, file to edit, or config to change) — doctor diagnoses AND prescribes, it never just lists problems.
Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/report-format.md") for ASCII report templates, JSON CI output schema, and exit codes.
Interpreting Results & Troubleshooting
Load Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/remediation-guide.md") for the full results interpretation table and troubleshooting steps for common failures (skills validation, build sync, memory).
Bisect with --safe-mode (CC 2.1.169+): when doctor findings don't explain a misbehaving session, restart with claude --safe-mode (or CLAUDE_CODE_SAFE_MODE=1) — it disables ALL customizations (CLAUDE.md, plugins incl. ork, skills, hooks, MCP). If the problem disappears, it's a customization; re-enable halves to isolate. If it persists, it's CC itself — file upstream.
After you fix an issue
CC 2.1.69+: Run /reload-plugins to activate plugin changes in the current session without restarting.
CC 2.1.116+: /reload-plugins and background plugin auto-update now auto-install missing plugin dependencies from marketplaces you've already added. If ork:doctor flagged a plugin-load failure due to a missing dep, /reload-plugins resolves it in place — no manual plugin install step needed.
CC 2.1.152+: For non-plugin skills in a skill directory (~/.claude/skills/ or .claude/skills/), run /reload-skills to re-scan without restarting — the skill analogue of /reload-plugins.
Chain: Deeper Audit
After a clean health report, audit the observability pipeline itself:
/ork:telemetry-inspect
doctor validates structure (manifests, hooks, skills, agents); /ork:telemetry-inspect validates the data plane — every telemetry writer's row count, schema lock, growth trend, and orphaned analytics files that structural checks don't cover.
Related Skills
ork:configure - Configure plugin settings
ork:telemetry-inspect - Audit the telemetry/analytics pipeline after a clean structural check
ork:quality-gates - CI/CD integration
security-scanning - Comprehensive audits
References
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/references/<file>") or Read("${CLAUDE_PLUGIN_ROOT}/skills/doctor/rules/<file>"):
File
Content
rules/diagnostic-checks.md
Bash commands and validation logic per category
rules/mcp-status-checks.md
Credential validation and misconfiguration detection
