---command: setup
description: Interactive setup wizard — install providers, configure auth, RTK, token optimization
aliases:
- sys-setup
allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion
---# Claude Octopus Setup
**Your first output line MUST be:** `🐙 Octopus Setup`
Interactive setup wizard. Detects what's installed, offers to install what's missing, configures auth, and optimizes token usage.
**This command auto-runs on first install** (via SessionStart hook). It also runs when users invoke `/octo:setup` manually.
**CRITICAL: This command MUST always run its interactive flow when invoked.** Never silently dismiss the user. Never say "you're already set up" without showing the dashboard and offering choices via AskUserQuestion. Even if everything is configured, the user invoked this command for a reason — show them their status and ask what they want to do.
## STEP 1: Detect Current State
Run a SINGLE comprehensive check:
```bash
set -euo pipefail
echo "=== Provider Detection ==="
printf "codex:%s\n" "$(command -v codex >/dev/null 2>&1 && echo installed || echo missing)"
printf "codex_auth:%s\n" "$(codex --version >/dev/null 2>&1 && echo ok || echo none)"
printf "gemini:%s\n" "$(command -v gemini >/dev/null 2>&1 && echo installed || echo missing)"
printf "agy:%s\n" "$(command -v agy >/dev/null 2>&1 && echo installed || echo missing)"
Render the setup status table from actual detection output. Do not hand-write or summarize this provider block; run this block and display its output exactly. The output MUST include the Antigravity line even when `agy` is missing.
if [[ -f "${GRAPHIFY_OUT_DIR}/graph.json" && -f "${GRAPHIFY_OUT_DIR}/GRAPH_REPORT.md" ]]; then graphify_graph_status="Graph available ✓"; else graphify_graph_status="Graph missing"; fi
if curl -sf --max-time 1 "${AGENTMEMORY_URL:-http://localhost:3111}/agentmemory/livez" >/dev/null 2>&1; then agentmemory_server_status="Running ✓"; else agentmemory_server_status="Not running"; fi
if command -v ollama >/dev/null 2>&1 && curl -sf http://localhost:11434/api/tags >/dev/null 2>&1; then ollama_status="Running ✓"; elif command -v ollama >/dev/null 2>&1; then ollama_status="Installed"; else ollama_status="Not installed"; fi
**If `MIGRATION_PROMPT_NEEDED` appears**, show this AskUserQuestion BEFORE the main menu:
```javascript
AskUserQuestion({
questions: [{
question: "v9.29.0 refreshed model defaults based on April 2026 benchmarks. Planning + security reviews now use Claude Opus 4.7 (best on SWE-bench Pro + LMArena). Code review + implementation stay on GPT-5.4 (best on Terminal-Bench + edge cases). Opus is ~2x the cost of GPT-5.4 per MTok — this will increase planning-phase cost. How would you like to proceed?",
header: "v9.29 Models",
multiSelect: false,
options: [
{label: "Accept new defaults (Recommended)", description: "Use Opus 4.7 for planning/strategy/security, GPT-5.4 for review/implementation"},
{label: "Keep v9.28 defaults (GPT-5.4 everywhere)", description: "Sets OCTOPUS_LEGACY_ROLES=1 in your shell profile"},
{label: "See the diff", description: "Show before/after routing table, then ask again"}
]
}]
})
```
**Route based on selection:**
- **Accept new defaults** → Write `model_defaults_v2=accepted` and `last_version=9.29.0` to `~/.claude-octopus/state.json`. Continue to STEP 3.
- **Keep v9.28 defaults** → Append `export OCTOPUS_LEGACY_ROLES=1` to the user's shell profile (detect `~/.zshrc` vs `~/.bashrc` via `$SHELL`), notify them to reload the shell, then write `model_defaults_v2=legacy` + `last_version=9.29.0`. Continue to STEP 3.
- **Open /octo:model-config** → Invoke that command. Do NOT write state — defer to whatever the user picks there.
- **See the diff** → Print the routing table below, then re-ask the question.
Cost impact (per MTok): Opus 4.7 $5/$25 vs GPT-5.4 $2.50/$15 — roughly 2x for planning phases.
Graceful fallback: roles requiring Opus silently downshift to GPT-5.4 if no Anthropic auth.
Opt-out anytime: OCTOPUS_LEGACY_ROLES=1
```
**WHY:** Existing users should not silently inherit the new defaults without a chance to opt out. The one-time prompt gates the behavior change on explicit consent, surfaces cost impact, and writes state so the prompt doesn't recur. Skip entirely for fresh installs (they have no prior mental model to migrate).
## STEP 3: Interactive Menu (ALWAYS show — even for returning users)
**Always present this menu after the dashboard, regardless of current setup state:**
```javascript
AskUserQuestion({
questions: [{
question: "What would you like to do?",
header: "Setup",
multiSelect: false,
options: [
{label: "Use Claude alone (recommended)", description: "Start immediately — Claude is built in. No extra setup needed. Add providers anytime via this menu."},
{label: "Add or configure a provider", description: "Install Codex, Gemini, Antigravity, Perplexity, Copilot, Qwen, OpenCode, or Vibe (Mistral)"},
{label: "Configure models", description: "Set which models are used for each workflow phase → launches /octo:model-config"},
{label: "Set up token optimization (RTK)", description: "Install RTK for 60-90% token savings on bash output"},
{label: "Set up Graphify companion", description: "Detect or install Graphify for optional knowledge-graph context"},
{label: "Set up memory companion", description: "Install or connect agentmemory for persistent cross-agent memory"},
{label: "Change work mode", description: "Switch between Dev mode and Knowledge Work mode"},
{label: "Set project tier", description: "Set OCTO_TIER=prototype|mvp|production as a routing hint"},
{label: "Antigravity CLI (agy)", description: "Install Google Antigravity CLI — adds the agy provider"},
{label: "Skip", description: "Continue with what's already installed"}
]
}]
})
```
Execute installs for each selected option. After each npm install completes, refresh PATH:
```bash
hash -r 2>/dev/null || rehash 2>/dev/null || true
```
This ensures the installed CLI (codex, gemini) is immediately available in the current shell without a restart.
For **Antigravity CLI (agy)**, first check whether `agy install` is available:
```bash
if command -v agy >/dev/null 2>&1; then
agy install
hash -r 2>/dev/null || rehash 2>/dev/null || true
agy models
else
echo "agy CLI not found; install Google Antigravity CLI first, then run: agy --version && agy models"
fi
```
If `agy` is not available yet, direct the user to install Google Antigravity CLI, then verify with `agy --version` and `agy models`. Octopus uses `OCTOPUS_AGY_MODEL` when set; when unset, `agy` uses its own built-in default model.
After install, offer auth:
```javascript
AskUserQuestion({
questions: [{
question: "How do you want to authenticate Codex?",
header: "Codex Auth",
multiSelect: false,
options: [
{label: "OAuth login (Recommended)", description: "codex login — opens browser, no API key needed"},
{label: "API key", description: "I'll set OPENAI_API_KEY manually"},
if ! source "${OCTO_ROOT}/scripts/lib/user-config.sh" 2>/dev/null; then
source "${PLUGIN_FALLBACK_ROOT}/scripts/lib/user-config.sh" 2>/dev/null || echo "Warning: could not load Octopus user-config helpers; setup preferences were not persisted."
fi
WORK_MODE_VALUE="dev" # dev, knowledge, or both based on user selection
if declare -f octo_config_write >/dev/null 2>&1; then
Skip this step when `SUPPORTS_PROMPT_CACHE_1H=false`. Otherwise:
```javascript
AskUserQuestion({
questions: [{
question: "Enable 1-hour prompt cache TTL? (Saves tokens on long /octo:embrace and /octo:loop sessions — the default is 5 minutes.)",
header: "Prompt Cache",
multiSelect: false,
options: [
{label: "Yes, enable 1-hour cache", description: "Adds ENABLE_PROMPT_CACHING_1H=1 to your shell profile — applies to Claude API/Bedrock/Vertex/Foundry."},
{label: "No, keep 5-minute default", description: "Simpler mental model; lower cost ceiling if you only run short sessions."}
]
}]
})
```
If "Yes", append `export ENABLE_PROMPT_CACHING_1H=1` to `~/.bashrc` (or `~/.zshrc` per `$SHELL`), only if not already present. Note to the user: this only affects Claude-to-Claude round-trips inside Claude Code. External CLI subshells (Codex, Gemini, Antigravity, Perplexity) are unaffected — their providers manage caching independently.
## STEP 4c: Project Tier Hint
`OCTO_TIER` is a routing and verification hint, not a hard policy.
```javascript
AskUserQuestion({
questions: [{
question: "What project tier should Octopus optimize for?",
header: "Tier",
multiSelect: false,
options: [
{label: "MVP (Recommended)", description: "Balanced checks, normal review, consensus on risky changes"},
{label: "Leave unset", description: "Use default balanced behavior without a project hint"}
]
}]
})
```
If a tier is selected, append `export OCTO_TIER=<prototype|mvp|production>` to the user's shell profile or project-local environment, only if not already present.
## Graphify Companion
Graphify is optional and is not a provider. If `graphify-out/GRAPH_REPORT.md` already exists, Octopus uses it as a compact architecture map for escalated workflows such as `/octo:review`; it does not build or refresh graphs automatically.
To install and initialize Graphify when the user opts in:
```bash
uv tool install graphifyy
graphify extract .
graphify claude install
graphify codex install
graphify hook install
```
Use `OCTOPUS_GRAPHIFY=0` to disable passive Graphify context injection.
## Memory Companion
agentmemory is optional and is not a provider. Octopus works without it. If agentmemory is installed and connected as an MCP server, Octopus can use it through the existing memory contract for cross-session context; if MCP tools are unavailable, Octopus falls back to the local REST bridge at `${AGENTMEMORY_URL:-http://localhost:3111}`.
To install and connect agentmemory when the user opts in:
```bash
npm install -g @agentmemory/agentmemory
agentmemory --version
agentmemory connect claude-code
```
For Codex or Cursor installs, use the matching connector instead:
If the user prefers not to install globally, use `npx -y @agentmemory/agentmemory@latest` in place of `agentmemory`. Use `OCTOPUS_MEMORY_BACKEND=agentmemory` to force Octopus to prefer agentmemory; `OCTOPUS_MEMORY_BACKEND=auto` detects an agentmemory MCP registration or `AGENTMEMORY_URL`.
## Remote/Web Session Defaults
If `remote_session:true` appears in the detection output, assume the user is in a Claude Code web/remote session. Do not launch interactive provider logins from this command. Explain that Octopus defaults to autonomous mode, skips provider probe calls, and uses the lightweight statusline unless overridden with:
```bash
export OCTOPUS_REMOTE_STATUSLINE=full
export OCTOPUS_REMOTE_STATUSLINE=off
```
## STEP 5: Verify & Summarize
Re-run provider detection to confirm everything works:
**Preflight — Ensure plugin root is resolvable (run via Bash tool FIRST):**
```bash
OCTO_ROOT="${HOME}/.claude-octopus/plugin"
if [[ ! -x "$OCTO_ROOT/scripts/orchestrate.sh" ]]; then
