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

1. Run the detector on the project root:

   python3 ${CLAUDE_SKILL_DIR}/scripts/detect_setup.py <project-root>
   

2. 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.

3. Cross-reference detection JSON against guide recommendations to identify what is missing or incomplete.

4. Detect MCP servers separately via Bash:

   claude mcp list
   

Phase 2: Configure

1. 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.

2. Walk through each selected category with targeted AskUserQuestion calls. See WORKFLOW.md for per-category question flows.

3. Show confirmation summary — table of all proposed CREATE/MODIFY/SKIP actions. Ask user to confirm before executing.

4. Execute changes — create files, install MCP servers, update settings.

5. Post-setup summary — show what was configured, next steps, and remind user they can re-run /devtools:code-env-setup for 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 user vs 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