/setup

command: setup
disable-model-invocation: true
description: Get Claude Octopus ready, verify it locally, or open advanced setup
aliases:
  - sys-setup
allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion

Claude Octopus Setup

**Your first output line MUST be:** `🐙 Octopus Setup`

The default path gets the user to a verified first success. It does not install optional companions, tune models, or contact a provider service. Every install, login, or configuration write requires an explicit choice first.

Always show the interactive setup choice when this command is invoked, even when the current readiness summary is already healthy.

Never ask the user to paste a secret into chat. Use the provider's login command or documented environment configuration. Never turn a failed recheck into a success message.

Default path

1. Resolve the installed plugin

Use the active plugin root when available, then the stable Octopus symlink. The fallback search is read-only; setup must not repair paths before the user has made a choice.

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
if [[ ! -r "$OCTO_ROOT/scripts/helpers/preflight.sh" ]]; then
  OCTO_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -r "$OCTO_ROOT/scripts/helpers/preflight.sh" ]]; then
  OCTO_ROOT="$(find "${HOME}/.claude/plugins/cache" "${HOME}/Library/Application Support/Claude" "${LOCALAPPDATA:-/dev/null}/Claude" "${XDG_DATA_HOME:-${HOME}/.local/share}/Claude" -maxdepth 8 -path '*/nyldn-plugins/octo/*/scripts/helpers/preflight.sh' -exec test -r '{}' \; -print -quit 2>/dev/null | sed 's#/scripts/helpers/preflight.sh$##')"
fi
[[ -r "$OCTO_ROOT/scripts/helpers/preflight.sh" ]] || {
  echo "Octopus installation not found. Reinstall octo@nyldn-plugins, then run /octo:setup again."
  exit 1
}
export OCTO_ROOT

1.25 Run installation health for troubleshooting

When setup is being rerun to troubleshoot installation, run this safe health pass immediately after resolving the root. It reads the installation Doctor category and both host cache locations. It does not create a stable link, record install state, clean a cache, log in, or contact a provider. A diagnostic exit status is evidence to show the user, not permission to claim the check passed.

setup_installation_health() {
  local doctor_json="" cache_json="" doctor_rc=0 cache_rc=0
  if [[ ! -r "$OCTO_ROOT/scripts/orchestrate.sh" ]]; then
    printf 'Installation health unavailable: orchestrate.sh is missing.\n'
    return 0
  fi

  if [[ -n "${CODEX_THREAD_ID:-}${CODEX_SANDBOX:-}" ]]; then
    doctor_json="$(env -u CLAUDE_PLUGIN_ROOT CODEX_PLUGIN_ROOT="$OCTO_ROOT" bash "$OCTO_ROOT/scripts/orchestrate.sh" doctor installation --json 2>/dev/null)" || doctor_rc=$?
    cache_json="$(env -u CLAUDE_PLUGIN_ROOT CODEX_PLUGIN_ROOT="$OCTO_ROOT" bash "$OCTO_ROOT/scripts/orchestrate.sh" cache-check --json 2>/dev/null)" || cache_rc=$?
  else
    doctor_json="$(env -u CODEX_PLUGIN_ROOT CLAUDE_PLUGIN_ROOT="$OCTO_ROOT" bash "$OCTO_ROOT/scripts/orchestrate.sh" doctor installation --json 2>/dev/null)" || doctor_rc=$?
    cache_json="$(env -u CODEX_PLUGIN_ROOT CLAUDE_PLUGIN_ROOT="$OCTO_ROOT" bash "$OCTO_ROOT/scripts/orchestrate.sh" cache-check --json 2>/dev/null)" || cache_rc=$?
  fi

  printf 'Installation health (read-only):\n'
  if [[ -n "$doctor_json" ]]; then
    printf '%s\n' "$doctor_json"
  else
    printf '%s\n' '{"error":"doctor installation returned no report"}'
  fi
  if [[ -n "$cache_json" ]]; then
    printf '%s\n' "$cache_json"
  else
    printf '%s\n' '{"error":"cache-check returned no report"}'
  fi
  printf 'installation-health-exit: doctor=%s cache=%s\n' "$doctor_rc" "$cache_rc"
}

setup_installation_health

1.5 Read resumable setup state

Read the receipt without creating files. The physical plugin root and host kind scope the receipt to this installation.

SETUP_STATE_HELPER="${OCTO_ROOT}/scripts/helpers/setup-state.py"
READINESS_CONTRACT_HELPER="${OCTO_ROOT}/scripts/helpers/readiness-contract.py"
[[ -r "$SETUP_STATE_HELPER" && -r "$READINESS_CONTRACT_HELPER" ]] || {
  echo "Octopus setup helpers are unavailable. Reinstall the plugin, then retry."
  exit 1
}
if [[ -n "${CODEX_THREAD_ID:-}${CODEX_SANDBOX:-}" ]]; then
  SETUP_HOST=codex
else
  SETUP_HOST=claude
fi
SETUP_ROOT="$(cd "$OCTO_ROOT" && pwd -P)"
SETUP_RECEIPT="$(jq -cn --arg host "$SETUP_HOST" --arg root "$SETUP_ROOT" \
  '{schema_version:1,action:"read",host:$host,plugin_root:$root}' |
  python3 "$SETUP_STATE_HELPER" --input -)" || {
  echo "Unable to read setup state safely. Fix the reported storage error before continuing."
  exit 1
}
SETUP_REVISION="$(jq -r '.revision' <<<"$SETUP_RECEIPT")"

setup_record() {
  local stage="$1" verification_json="$2" request response
  request="$(jq -cn \
    --arg host "$SETUP_HOST" --arg root "$SETUP_ROOT" \
    --arg flow "$SETUP_FLOW" --arg provider "$SETUP_PROVIDER" \
    --arg stage "$stage" --argjson revision "$SETUP_REVISION" \
    --argjson verification "$verification_json" \
    '{schema_version:1,action:"record",host:$host,plugin_root:$root,
      expected_revision:$revision,flow:$flow,provider:$provider,stage:$stage,
      verification:$verification}')" || return 1
  response="$(printf '%s\n' "$request" |
    python3 "$SETUP_STATE_HELPER" --input -)" || return $?
  SETUP_REVISION="$(jq -r '.revision' <<<"$response")"
  SETUP_LAST_RESPONSE="$response"
  printf '%s\n' "$response"
}

setup_fail_recheck() {
  local reason="$1" checked_at="${2:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}" verification_json
  verification_json="$(jq -cn --arg reason "$reason" --arg checked "$checked_at" \
    '{result:"failed",reason_code:$reason,checked_at:$checked}')" || return 1
  setup_record rechecked "$verification_json" >/dev/null
}

setup_invalidate_existing() {
  local reason="$1"
  [[ "$(jq -r '.found' <<<"$SETUP_RECEIPT")" == true ]] || return 0
  SETUP_FLOW="$(jq -r '.record.flow' <<<"$SETUP_RECEIPT")"
  SETUP_PROVIDER="$(jq -r '.record.provider' <<<"$SETUP