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

Interpreting Results

Healthy Output

All checks pass — no action needed.

Common Issues and Fixes

Integration with Other Skills

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_PROFILE value (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

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.md and .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