Claude Code Setup Wizard
Interactive environment setup following the Claude Code Guide.
Pre-flight
Run the detection script to understand current state:
python3 ${CLAUDE_SKILL_DIR}/scripts/detect_setup.py
Two-Phase Workflow
Phase 1: Detect
- Run the detector on the project root:
``bash python3 ${CLAUDE_SKILL_DIR}/scripts/detect_setup.py <project-root> ``
- Fetch the guide via WebFetch:
`` https://raw.githubusercontent.com/joaquimscosta/arkhe-claude-plugins/main/docs/CLAUDE_CODE_GUIDE.md `` If WebFetch fails (network error, 404), warn the user and proceed using LLM knowledge only.
- Cross-reference detection JSON against guide recommendations to identify what is missing or incomplete.
- Detect MCP servers separately via Bash:
``bash claude mcp list ``
Phase 2: Configure
- Present category selection using
AskUserQuestion(multiSelect: true). Show detection status for each category (configured / partially configured / not configured):
| # | Category | Guide Section | What It Configures | |---|----------|---------------|--------------------| | 1 | Global CLAUDE.md | Section 1 | ~/.claude/CLAUDE.md — security NEVER rules, account config | | 2 | Project Scaffolding | Section 2 | .claude/ dirs, .env.example, .gitignore, CLAUDE.md | | 3 | MCP Servers | Section 3 | Install recommended servers via claude mcp add | | 4 | Hooks | Section 7 | ~/.claude/hooks/block-secrets.py, hooks in settings.json | | 5 | Custom Agents | Section 10 | ~/.claude/agents/ starter agent files | | 6 | Keybindings | Section 13 | ~/.claude/keybindings.json | | 7 | Settings | Section 13 | Language, background tasks in settings.json |
If user passed a specific category as argument (e.g., /devtools:code-env-setup hooks), skip the selection and go directly to that category.
- Walk through each selected category with targeted
AskUserQuestioncalls. See [WORKFLOW.md](WORKFLOW.md) for per-category question flows.
- Show confirmation summary — table of all proposed CREATE/MODIFY/SKIP actions. Ask user to confirm before executing.
- Execute changes — create files, install MCP servers, update settings.
- Post-setup summary — show what was configured, next steps, and remind user they can re-run
/devtools:code-env-setupfor incremental updates.
Key Rules
- Never overwrite existing files without asking. Always offer merge/replace/skip.
- Detect first — skip items already configured.
- Use AskUserQuestion for every decision. Do not assume user preferences.
- Merge settings — when updating settings.json, read existing content first and deep-merge.
- MCP servers — ask scope (global
-s uservs project-s project) before installing.
Guide Reference
Fetch at runtime — do not cache or embed:
- Claude Code Guide:
https://raw.githubusercontent.com/joaquimscosta/arkhe-claude-plugins/main/docs/CLAUDE_CODE_GUIDE.md
References
- Workflow: See [WORKFLOW.md](WORKFLOW.md) for per-category setup flows
- Examples: See [EXAMPLES.md](EXAMPLES.md) for example setup sessions
- Troubleshooting: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
- Detection Script: See [scripts/detect_setup.py](scripts/detect_setup.py) for detection logic