From octo
Runs diagnostics on Claude Octopus plugin environment across 11 categories: providers, auth, config, hooks, scheduler, state, skills, and more. Use for setup verification and issue detection.
npx claudepluginhub nyldn/claude-octopus --plugin octoThis skill uses the workspace's default tool permissions.
Run environment diagnostics across 11 check categories. Identifies misconfigured providers, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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.
Use this skill when:
Do NOT use for:
/octo:setup — it guides configuration)/octo:status)/octo:debug)cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor
This runs all 11 check categories and displays a formatted report.
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
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.
# 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
| 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 |
All checks pass — no action needed.
| 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 |
| 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 |
Claude Octopus hooks can run in different profiles to balance cost and coverage.
Current profile: $OCTO_HOOK_PROFILE (default: standard)
Available profiles:
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).
The doctor reports the active intensity profile — a single knob controlling hook gating, model selection, phase skipping, and context verbosity.
OCTO_PROFILE value (budget/balanced/quality, default: balanced)OCTO_HOOK_PROFILE, or auto-selected from intent| 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 |
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.
.octopus/RUNTIME.md and .claude-octopus/RUNTIME.md)cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.mdWithout 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.
| 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 |