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:
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.mdIf 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:
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 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 for per-category setup flows
- Examples: See EXAMPLES.md for example setup sessions
- Troubleshooting: See TROUBLESHOOTING.md for common issues
- Detection Script: See scripts/detect_setup.py for detection logic