skill-doctor

Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex.

Cross-reference commands use installed skill names in Codex rather than /octo:* slash commands.

Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.

For host tool equivalents, see skills/blocks/codex-host-adapter.md.

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: Resolve Plugin Root and Run Full Diagnostics

Use this resolver before running Octopus scripts. Do not assume ~/.claude-octopus/plugin exists; Windows Git Bash installs may not support the stable symlink. Run this as a single Bash call.

OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
  OCTO_BIN="$(command -v octopus)"
  OCTO_PLUGIN_ROOT="$(cd "$(dirname "$OCTO_BIN")/.." && pwd)"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="$(
    find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
      | sed 's#/scripts/orchestrate.sh$##' \
      | grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' \
      | sort \
      | tail -1
  )"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."
  exit 1
fi
mkdir -p "${HOME}/.claude-octopus"
_octo_stable="${HOME}/.claude-octopus/plugin"
if [[ ! -L "$_octo_stable" ]] || [[ "$(cd "$OCTO_PLUGIN_ROOT" 2>/dev/null && pwd -P)" != "$(cd "$_octo_stable" 2>/dev/null && pwd -P)" ]]; then
  [[ -L "$_octo_stable" || -f "$_octo_stable" ]] && rm -f "$_octo_stable" 2>/dev/null || true
  ln -s "$OCTO_PLUGIN_ROOT" "$_octo_stable" 2>/dev/null || true
fi
unset _octo_stable
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/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:

bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor providers
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor auth
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor config
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor state
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor smoke
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor hooks
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor scheduler
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor skills
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor conflicts
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor agents
bash "${HOME}/.claude-octopus/plugin/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. Antigravity CLI (agy) setup is detected and reported with install guidance. 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
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose
bash "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" doctor auth --verbose

Step 5: Interactive Remediation (MANDATORY for fixable issues)

After running diagnostics, if ANY fixable issues are found, you MUST use AskUserQuestion to offer fixes. Do NOT just print instructions — offer to execute them.

RTK not installed:

AskUserQuestion({
  questions: [{
    question: "RTK saves 60-90% on bash output tokens. Install it now?",
    header: "Install RTK",
    multiSelect: false,
    options: [
      {label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},
      {label: "Install via cargo", description: "cargo install rtk-token-killer"},
      {label: "Skip", description: "Continue without RTK"}
    ]
  }]
})

If user chooses install, run it, then offer hook setup.

RTK installed but hook not configured on macOS/Linux:

On Windows Git Bash, do not offer rtk init -g. RTK uses CLAUDE.md injection mode there, so report the hook check as skipped.

AskUserQuestion({
  questions: [{
    question: "RTK is installed but the Claude Code hook isn't active. Configure it?",
    header: "RTK Hook",
    multiSelect: false,
    options: [
      {label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},
      {label: "Skip", description: "I'll configure it later"}
    ]
  }]
})

Missing optional providers:

AskUserQuestion({
  questions: [{
    question: "Some providers are missing. Install them?",
    header: "Providers",
    multiSelect: true,
    options: [
      {label: "Codex CLI", description: "npm install -g @openai/codex"},
      {label: "Gemini CLI", description: "brew install gemini-cli (macOS)"},
      {label: "Antigravity CLI", description: "Install agy, then verify with agy --version && agy models"},
      {label: "Skip all", description: "Continue with available providers"}
    ]
  }]
})

Auth expired: Offer to run the login command for the expired provider.

Multiple fixable issues: Batch them into a single AskUserQuestion with multiSelect where appropriate, rather than asking one at a time.

Check Categories

| Category | What it checks | |----------|---------------| | providers | Claude Code version, Codex CLI installed, Gemini CLI installed, Antigravity 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, G