Moliboy5000 Environment Doctor
Overview
Run environment diagnostics across 11 check categories. Identifies misconfigured providers, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly.
Core principle: Detect problems before they surface in workflows.
When to Use
Use this skill when:
- Something isn't working and you're not sure why
- After installing or updating the plugin
- Before a demo or important workflow run
- Checking if providers are properly authenticated
- Verifying scheduler, hooks, or skills are correctly configured
Do NOT use for:
- First-time setup (use
/octo:setup— it guides configuration) - Project workflow status (use
/octo:status) - Debugging application code (use
/octo:debug)
The Process
Step 1: Run Full Diagnostics
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor
This runs all 11 check categories and displays a formatted report.
Step 2: Filter by Category (Optional)
If the user asks about a specific area, filter:
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor providers
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor config
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor state
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor smoke
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor hooks
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor scheduler
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor skills
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor conflicts
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor agents
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor recurrence
Step 3: Check & Install Dependencies
Run the dependency checker to find missing CLIs, statusline config, and recommended plugins:
bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" check
If the check reports missing deps, offer to install them:
bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" install
This auto-installs: Codex CLI, Gemini CLI, jq, and the statusline resolver. For plugins (claude-mem, document-skills), it prints /plugin install commands the user must run manually.
Step 4: Verbose or JSON Output
# Detailed output for troubleshooting
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --verbose
# Machine-readable output
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --json
# Combine: specific category + verbose
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth --verbose
Check Categories
| Category | What it checks |
|---|---|
providers |
Claude Code version, Codex CLI installed, Gemini CLI installed, Perplexity API key, Ollama local LLM (server + models), circuit breaker status, provider fallback history |
auth |
Authentication status for each provider |
config |
Plugin version, install scope, feature flags |
state |
Project state.json, stale results, workspace writable |
smoke |
Smoke test cache, model configuration |
hooks |
hooks.json validity, hook scripts |
scheduler |
Scheduler daemon, jobs, budget gates, kill switches |
skills |
Skill files loaded and valid |
conflicts |
Conflicting plugins detection |
agents |
Agent definitions, worktree isolation, CLI registration, version compatibility |
recurrence |
Failure pattern detection — flags repeated quality gate failures, source hotspots, 48h trends |
deps |
Software dependencies — Node.js, jq, Codex/Gemini CLIs, RTK token compression, statusline resolver, recommended plugins |
Interpreting Results
Healthy Output
All checks pass — no action needed.
Common Issues and Fixes
| Issue | Fix |
|---|---|
| Codex CLI not found | npm install -g @openai/codex or install via codex login |
| Gemini CLI not found | Install Gemini CLI from Google |
| Perplexity not configured | export PERPLEXITY_API_KEY="pplx-..." (optional) |
| Auth expired | Re-run codex login or gemini login |
| Circuit breaker OPEN | Provider had 3+ consecutive transient failures — wait for cooldown or check provider status |
| Stale state | Delete .octo/state.json and re-initialize |
| Invalid hooks.json | Check hooks.json syntax — must be valid JSON |
| RTK not installed | brew install rtk && rtk init -g (optional — saves 60-90% tokens on bash output) |
| Conflicting plugins | Uninstall conflicting plugins or adjust scope |
Integration with Other Skills
| Scenario | Route |
|---|---|
| Doctor finds missing provider | Suggest /octo:setup to configure |
| Doctor finds stale project state | Suggest /octo:status to review |
| Doctor finds hook errors | Guide user to fix hooks.json |
| All checks pass, user still has issues | Suggest /octo:debug for deeper investigation |
Hook Profile
Claude Octopus hooks can run in different profiles to balance cost and coverage.
Current profile: $OCTO_HOOK_PROFILE (default: standard)
Available profiles:
- minimal — Only session lifecycle and cost tracking hooks (lowest overhead)
- standard — All hooks except expensive review/security gates (default)
- strict — All hooks enabled including quality and security gates
Override: Set OCTO_PROFILE=budget|balanced|quality or OCTO_DISABLED_HOOKS=hook1,hook2 to fine-tune. Legacy OCTO_HOOK_PROFILE still works (minimal→budget, standard→balanced, strict→quality).
Intensity Profile
The doctor reports the active intensity profile — a single knob controlling hook gating, model selection, phase skipping, and context verbosity.
What the Doctor Checks
- Current profile:
OCTO_PROFILEvalue (budget/balanced/quality, default: balanced) - Profile source: env var, legacy
OCTO_HOOK_PROFILE, or auto-selected from intent - Hook gating: which hooks are enabled/disabled at this profile level
- Model hints: which model (sonnet/opus) is recommended for each phase
- Context verbosity: compressed/standard/full
Profile Summary
| Dimension | budget | balanced | quality |
|---|---|---|---|
| Hooks | essential only | standard (no quality gates) | all hooks |
| Models | Sonnet everywhere | Sonnet + Opus for synthesis | Opus for most phases |
| Phases | Skip discover if context given | Skip re-discovery | All phases run |
| Context | Compressed | Standard | Full inlining |
Runtime Context
The doctor checks for project-level RUNTIME.md — a file that provides project-specific context (API endpoints, env vars, test commands, build steps) to orchestration prompts.
What the Doctor Checks
- RUNTIME.md exists in the project root (also checks
.octopus/RUNTIME.mdand.claude-octopus/RUNTIME.md) - If missing, suggest creating one from the template:
cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md - If present, confirm it contains at least one populated section (not just the template defaults)
Why It Matters
Without a RUNTIME.md, orchestration prompts lack project-specific details — leading to generic advice about test commands, environment variables, and build steps. A populated RUNTIME.md makes every workflow more accurate.
Quick Reference
| User Input | Action |
|---|---|
/octo:doctor |
Run all 11 categories |
/octo:doctor providers |
Check provider installation only |
/octo:doctor auth --verbose |
Detailed auth status |
/octo:doctor --json |
Machine-readable output |