Stats
Actions
Tags
From octo
Runs 11 categories of environment diagnostics for Claude Octopus — checks providers, auth, config, hooks, and scheduler to find misconfigurations before they cause workflow failures.
How this skill is triggered — by the user, by Claude, or both
Slash command
/octo:skill-doctorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
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, seeskills/blocks/codex-host-adapter.md.
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)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.
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
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.
# 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
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.
| 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, Gemini, Antigravity CLIs, RTK token compression (gain stats + hook status), 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 |
| Antigravity CLI not found | Install agy, then verify with agy --version and agy models |
| 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 | Offer to install: brew install rtk && rtk init -g (saves 60-90% tokens). Use AskUserQuestion to offer brew vs cargo install. |
| RTK installed but hook not configured | On macOS/Linux, offer rtk init -g; on Windows Git Bash, report skipped because RTK uses CLAUDE.md injection mode |
| RTK gain stats unavailable | Run some bash commands first, then check rtk gain to see token savings |
| 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 |
Also report OCTO_TIER when set. This is a recommendation hint, not a hard policy.
| Tier | Doctor guidance |
|---|---|
prototype | Prefer faster checks and warn before high-cost provider fanout |
mvp | Use balanced defaults and consensus on risky changes |
production | Recommend full verification, security review, and stricter release gates |
If unset, show OCTO_TIER=unset and suggest setting it only when the project has a stable risk profile.
If CLAUDE_CODE_REMOTE=true or OCTOPUS_REMOTE_SESSION=true, report:
OCTOPUS_REMOTE_STATUSLINE=fullSuggest /octo:setup only for configuration guidance; do not recommend interactive provider logins inside the remote session.
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.
/octo:doctor was removed in v9.41.0 to preserve Claude Code's native /doctor command.
Invoke this skill by asking Claude naturally, or run the orchestrator directly:
| What to say / run | Action |
|---|---|
| "run Octopus doctor diagnostics" | Run all 11 categories |
| "check Octopus providers" | Check provider installation only |
bash scripts/orchestrate.sh doctor auth --verbose | Detailed auth status |
bash scripts/orchestrate.sh doctor --json | Machine-readable output |
npx claudepluginhub nyldn/claude-octopus --plugin octoAudits Claude Code project configuration for drift and collaboration issues across six layers (CLAUDE.md, rules, skills, hooks, subagents, verifiers), tiered by project complexity.
Audits Claude Code configurations for best practices in skills, instructions, MCP servers, hooks, plugins, security, over-engineering, and context efficiency via file scans and focused checks. Invoke with /claudit [focus-area].
Sets up Claude Code projects with config files and audits existing ones for permissions, context quality, MCP coverage, leaked secrets, stale docs, and cruft. Uses sub-agents for analysis.