[bot:cli-maxxing] Claude-first: upfront sub gate + retry-hardened install (2026-04-17)

Nathan's ask: users should be warned about the paid claude.ai
requirement BEFORE the 20-min install downloads anything, and the
Claude Code install itself must not fail silently — it's the one
tool everything else depends on.

install.sh:
  - Subscription gate banner immediately after opening title, before
    Step 1 runs. Prompts "Press Enter to continue" if stdin is a tty;
    gracefully continues with a warning in non-interactive mode.
    Directs to https://claude.ai/ with Pro/Max guidance.
  - Hard gate after Step 1 + reload_path: runs `claude --version` and
    exits 1 with a clear troubleshooting banner if it doesn't work.
    Stops the pipeline instead of configuring downstream steps against
    a missing binary.

step-1-install.sh / install_claude_code:
  - Retry loop (3 attempts, 5s/10s backoff) around `npm install -g
    @anthropic-ai/claude-code`.
  - Each attempt rehydrates nvm so the shim dir is visible.
  - Hard verify via `claude --version` (execution, not just PATH
    presence) — surfaces broken installs instead of claiming success.
  - "already installed" branch also now verifies execution.

README.md:
  - Prominent [!IMPORTANT] callout at the top of "Before You Start"
    warning about the paid subscription requirement and linking to
    claude.ai. Notes that the installer prompts upfront.

Shellcheck clean at warning+.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: fidgetcoding

README.md

@@ -45,6 +45,13 @@ Install `cli-maxxing` first. `creativity-maxxing` and `2ndbrain-maxxing` can be
 
 [Back to top](#quick-nav)
 
+> [!IMPORTANT]
+> **You need a paid [claude.ai](https://claude.ai) subscription before anything below is useful.**
+>
+> The Claude Code CLI installs for free — but USING Claude requires a paid plan. If you don't have one yet, [sign up first](https://claude.ai) (Claude Pro is the minimum tier at $20/mo; Max is recommended for heavy use). Otherwise the installer downloads ~500 MB of tooling that has nothing to talk to.
+>
+> The installer will prompt you upfront — press Enter if you're subscribed, Ctrl+C to bail and sign up first.
+
 - Your computer needs to be from roughly **2020 or later** (macOS Big Sur+ or a recent Linux).
 - You need an **internet connection** since the scripts download everything live.
 - **Don't run it as root.** Just open your terminal normally and paste the command.

install.sh

@@ -9,6 +9,7 @@ set -uo pipefail
 # Usage: bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/install.sh)
 # =============================================================================
 
+RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
@@ -53,13 +54,63 @@ echo -e "${BLUE}  Running all steps in order, skipping what's already done${NC}"
 echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
 
+# Subscription gate — before any downloads. The CLI is free; Claude itself
+# requires a paid claude.ai plan. No plan = the whole install is wasted time,
+# so catch it upfront instead of after 20 min of brew + MCP downloads.
+echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${YELLOW}  IMPORTANT — Claude subscription required${NC}"
+echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo "  This installer sets up Claude Code (the terminal CLI) for free,"
+echo "  but USING Claude requires a paid claude.ai plan. No plan = the"
+echo "  rest of this install is wasted time."
+echo ""
+echo -e "  No plan yet?  Sign up:  ${GREEN}https://claude.ai/${NC}"
+echo "    • Claude Pro is the minimum tier (\$20/mo)"
+echo "    • Max plan recommended for heavy use"
+echo ""
+echo -e "  Already subscribed?  ${GREEN}Press Enter${NC} to continue."
+echo -e "  Need to sign up first?  ${GREEN}Press Ctrl+C${NC}, come back after."
+echo ""
+if [ -t 0 ]; then
+    # shellcheck disable=SC2162
+    read -p "  Press Enter to continue... " _CLAUDE_SUB_CONFIRM || true
+else
+    echo -e "${YELLOW}  [non-interactive mode — continuing. Make sure you have a plan.]${NC}"
+fi
+echo ""
+
 # Step 1
 echo -e "${YELLOW}>>> Step 1 — Get Claude Running${NC}"
 echo ""
 curl -fsSL "$BASE_URL/step-1/step-1-install.sh" | bash
 # BUG A fix: Step 1 installs brew+nvm; re-source them into this shell so the
 # remaining curl|bash steps (Ghostty/Arc/2/3/9/final) can actually find them.
 reload_path
+
+# Hard gate: if claude didn't land, stop everything. Every downstream step
+# configures Claude integrations — pointless without claude actually working.
+if ! command -v claude &>/dev/null || ! claude --version &>/dev/null; then
+    echo ""
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${RED}  CRITICAL — Claude Code did not install${NC}"
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    echo "  Step 1 finished but 'claude --version' does not work. Without"
+    echo "  claude on PATH, the remaining steps can't configure anything"
+    echo "  useful — stopping here."
+    echo ""
+    echo "  Most common causes + fixes:"
+    echo "    1. Fresh terminal needed — close this window, open a new one,"
+    echo "       run 'claude --version'. If it works, re-run this installer."
+    echo "    2. npm registry blocked — check internet; try again."
+    echo "    3. Old Node.js — 'node -v' should report v18 or higher."
+    echo ""
+    echo "  Fix one of the above, then re-run:"
+    echo -e "    ${GREEN}bash <(curl -fsSL https://raw.githubusercontent.com/lorecraft-io/cli-maxxing/main/install.sh)${NC}"
+    echo ""
+    exit 1
+fi
 echo ""
 
 # Bonus — Ghostty Terminal (optional, won't reinstall if already present)

step-1/step-1-install.sh

@@ -296,15 +296,42 @@ install_node() {
 #    where the passwd shell is bash but Terminal actually runs zsh.
 # -----------------------------------------------------------------------------
 install_claude_code() {
-    if command -v claude &>/dev/null; then
-        success "Claude Code already installed"
+    if command -v claude &>/dev/null && claude --version &>/dev/null; then
+        success "Claude Code already installed ($(claude --version 2>/dev/null))"
     else
-        info "Installing Claude Code..."
-        npm install -g @anthropic-ai/claude-code 2>/dev/null \
-            || sudo npm install -g @anthropic-ai/claude-code
+        info "Installing Claude Code (the single most important tool — retrying up to 3x)..."
+        local attempt=0
+        local max_attempts=3
+        local installed=0
+        while [ $attempt -lt $max_attempts ]; do
+            attempt=$((attempt + 1))
+            if npm install -g @anthropic-ai/claude-code 2>/dev/null \
+                || sudo npm install -g @anthropic-ai/claude-code; then
+                # Rehydrate nvm in case the shim dir just got populated.
+                export NVM_DIR="$HOME/.nvm"
+                # shellcheck source=/dev/null
+                [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+                if command -v claude &>/dev/null && claude --version &>/dev/null; then
+                    installed=1
+                    break
+                fi
+            fi
+            if [ $attempt -lt $max_attempts ]; then
+                local backoff=$((attempt * 5))
+                warn "Claude Code install attempt $attempt/$max_attempts failed — retrying in ${backoff}s..."
+                sleep "$backoff"
+            fi
+        done
+
+        if [ $installed -ne 1 ]; then
+            fail "Claude Code installation failed after $max_attempts attempts. Check internet + npm registry access (https://registry.npmjs.org/), then re-run this installer."
+        fi
 
-        command -v claude &>/dev/null || fail "Claude Code installation failed"
-        success "Claude Code installed"
+        # Final hard verify: the binary must execute, not just exist on PATH.
+        if ! claude --version &>/dev/null; then
+            fail "Claude Code installed but 'claude --version' does not execute. Try opening a new terminal and running 'claude --version'; if that works, re-run the installer."
+        fi
+        success "Claude Code installed ($(claude --version 2>/dev/null))"
     fi
 
     # Add Claude Code shortcuts to every RC file. Idempotent per-file — re-runs