Code Env Setup

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):

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

Claude Setup Examples

Example 1: Fresh Environment

A developer with no existing Claude Code configuration runs /devtools:code-env-setup for the first time.

Detection Output

{
  "global": {
    "claude_md": {"exists": false},
    "settings_json": {"exists": false},
    "keybindings_json": {"exists": false},
    "hooks_dir": {"exists": false},
    "agents_dir": {"exists": false}
  },
  "project": {
    "claude_md": {"exists": false},
    "claude_dir": {"exists": false, "has_skills": false, "has_agents": false, "has_commands": false},
    "env_example": {"exists": false},
    "gitignore": {"exists": true, "has_env_rule": false},
    "src_dir": {"exists": true},
    "tests_dir": {"exists": false},
    "docs_dir": {"exists": false},
    "scripts_dir": {"exists": false}
  }
}

Interaction Flow

1. Category selection: User selects all 7 categories (everything shows "not configured")

2. Global CLAUDE.md: User selects all 3 security rules, provides GitHub username "jdoe", chooses HTTPS, provides git identity

3. Project Scaffolding: User selects .env.example, updates .gitignore (add .env rule), CLAUDE.md, .claude/ dirs, tests/, docs/, scripts/ (skips src/ — already exists)

4. MCP Servers: User selects Context7, Sequential Thinking (global scope)

5. Hooks: User selects block-secrets hook only

6. Custom Agents: User selects code-reviewer (personal scope)

7. Keybindings: User selects all 4 recommended shortcuts

8. Settings: English, background tasks enabled

9. Confirmation: 12 creates, 2 installs, 1 settings update. User confirms.

10. Post-setup: All items show as completed.

---

Example 2: Partial Setup

A developer who already has Global CLAUDE.md and some MCP servers runs /devtools:code-env-setup to fill gaps.

Detection Output

{
  "global": {
    "claude_md": {"exists": true, "size_bytes": 856},
    "settings_json": {"exists": true, "has_hooks": false},
    "keybindings_json": {"exists": false},
    "hooks_dir": {"exists": false},
    "agents_dir": {"exists": true, "count": 1}
  },
  "project": {
    "claude_md": {"exists": true},
    "claude_dir": {"exists": true, "has_skills": true, "has_agents": false, "has_commands": true},
    "env_example": {"exists": true},
    "gitignore": {"exists": true, "has_env_rule": true},
    "src_dir": {"exists": true},
    "tests_dir": {"exists": true},
    "docs_dir": {"exists": true},
    "scripts_dir": {"exists": true}
  }
}

Interaction Flow

1. Category selection: Shows status indicators:

• Global CLAUDE.md — configured
• Project Scaffolding — configured
• MCP Servers — partially configured (2 of 3 core servers)
• Hooks — not configured
• Custom Agents — partially configured (1 agent)
• Keybindings — not configured
• Settings — partially configured

User selects: Hooks, Keybindings, MCP Servers

2. MCP Servers: Only shows servers not yet installed. User adds Sequential Thinking.

3. Hooks: User selects block-secrets hook.

4. Keybindings: User selects 2 of 4 shortcuts.

5. Confirmation: 3 creates, 1 install, 1 settings update. User confirms.

---

Example 3: Single Category

A developer runs /devtools:code-env-setup hooks to only configure hooks.

Interaction Flow

1. Detection runs — focuses on hooks-related state

2. Skips category selection — goes directly to Hooks category

3. Hooks: User selects block-secrets hook and Setup hook

4. Confirmation: 1 file create, 1 settings update

5. Post-setup: Shows hooks-only summary with next steps

Claude Setup Troubleshooting

WebFetch Fails

Symptom: Cannot fetch the Claude Code Guide from GitHub.

Cause: Network restrictions, GitHub rate limiting, or URL change.

Fix: The skill proceeds with LLM knowledge only. All setup categories still work — the guide just provides additional context. If you need the latest guide content, read it locally:

docs/CLAUDE_CODE_GUIDE.md

---

Permission Denied on ~/.claude/

Symptom: Cannot create files in ~/.claude/ directory.

Cause: Directory permissions or ownership issues.

Fix:

# Check ownership
ls -la ~/.claude/

# Fix permissions if needed
chmod 755 ~/.claude/

---

MCP Server Install Fails

Symptom: claude mcp add command fails.

Cause: Node.js or npx not installed, or package not found.

Fix: 1. Verify Node.js is installed: node --version (requires v18+) 2. Verify npx is available: npx --version 3. Try installing the server manually with the full command from the guide 4. For Python-based servers (Docling), verify uvx is available

---

Settings.json Merge Conflict

Symptom: Existing settings get overwritten or corrupted.

Cause: The skill read/write cycle encountered malformed JSON.

Fix: 1. Check ~/.claude/settings.json for syntax errors:

   python3 -m json.tool ~/.claude/settings.json

2. If corrupted, restore from backup or recreate manually 3. Re-run /devtools:code-env-setup for the affected category

---

Detection Script Errors

Symptom: detect_setup.py fails or returns unexpected output.

Cause: Python version too old or permission issues.

Fix: 1. Verify Python 3.8+: python3 --version 2. Run manually to see errors:

   python3 ${CLAUDE_SKILL_DIR}/scripts/detect_setup.py

3. The skill can proceed without detection — it will ask about everything instead of auto-detecting.

---

Hooks Not Triggering

Symptom: Block-secrets hook is configured but doesn't prevent file access.

Cause: Hook script not executable, wrong path, or settings.json not in the right location.

Fix: 1. Verify script is executable: ls -la ~/.claude/hooks/block-secrets.py 2. Verify settings.json is at ~/.claude/settings.json (not project-level) 3. Check the hook command path matches the actual file location 4. Test manually:

   echo '{"tool_input":{"file_path":".env"}}' | python3 ~/.claude/hooks/block-secrets.py

Should exit with code 2.

---

Re-running Setup

The skill is designed for incremental updates. Running /devtools:code-env-setup again will:

• Detect what is already configured
• Skip completed items
• Offer to add new items or modify existing ones
• Never overwrite without asking

Claude Setup Workflow

Detailed per-category setup flows. Each category follows the pattern: detect existing state, ask user preferences via AskUserQuestion, show confirmation, then execute.

---

Category 1: Global CLAUDE.md

Detect: Check detection.global.claude_md.exists

If exists: Read the file, summarize contents, then AskUserQuestion:

• Merge new rules into existing file
• Replace entirely with recommended template
• Skip this category

If missing: AskUserQuestion (multiSelect: true) — which security rules to include:

• NEVER publish sensitive data (passwords, API keys, tokens to git/npm/docker)
• NEVER commit .env files (always verify .env in .gitignore)
• NEVER read or expose secrets (.env, credentials, SSH keys, service account keys)

Then ask account configuration (use "Other" for text input):

• GitHub username
• Git protocol: HTTPS (recommended) or SSH
• Git identity: name and email
• Docker Hub username (optional)

Execute: Write ~/.claude/CLAUDE.md with selected rules and account config. Follow the template from Guide Section 1.

---

Category 2: Project Scaffolding

Detect: Check detection.project.* fields

AskUserQuestion (multiSelect: true) — which items to create (skip items that already exist, show them as "already configured"):

• .env.example — template with placeholder values
• .gitignore — with .env, node_modules/, dist/, .env.local, .env.production
• CLAUDE.md — project overview template
• .claude/skills/ directory
• .claude/agents/ directory
• .claude/commands/ directory
• src/ directory
• tests/ directory
• docs/ directory
• scripts/ directory

Execute: Create selected directories with mkdir -p via Bash. Create selected files with Write tool using appropriate templates.

Templates

.env.example:

# Application Configuration
# Copy to .env and fill in real values
# NEVER commit .env to git

# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
# API_KEY=your-api-key-here
# SECRET_KEY=your-secret-key-here

.gitignore (append to existing or create):

# Environment
.env
.env.local
.env.production
.env.*

# Dependencies
node_modules/
vendor/

# Build
dist/
build/
target/
*.pyc
__pycache__/

# IDE
.idea/
.vscode/
*.swp

CLAUDE.md (project template):

# CLAUDE.md

## Project Overview

[Brief description of the project]

## Development Commands

Install dependencies

Run tests

Build

Lint

## Architecture

[Key architecture decisions and patterns]

## Conventions

[Coding conventions and style guidelines]

---

Category 3: MCP Servers

Detect: Run claude mcp list via Bash to get currently installed servers.

Cross-reference against the guide's recommended servers (Section 3). Group by category:

AskUserQuestion — MCP server scope:

• Global (available in all projects, -s user)
• Project-only (this project only, -s project)

AskUserQuestion (multiSelect: true) per server group — skip servers already installed:

Core Development:

• Context7 — Live docs for any library
• Filesystem — Advanced file operations
• Sequential Thinking — Structured problem-solving

Databases (ask only if relevant to project):

• MongoDB — Atlas/Community
• PostgreSQL — Query Postgres naturally
• DBHub — Universal (MySQL, SQLite, etc.)

Documents & RAG:

• Docling — PDF/DOCX parsing
• Qdrant — Vector search
• Chroma — Embeddings, vector DB

Browser & Testing:

• Browser MCP — Use your logged-in Chrome

Cloud & DevOps:

• AWS — S3, Lambda, CloudWatch
• Docker — Container management
• Kubernetes — Cluster operations

Execute: For each selected server, run the corresponding claude mcp add command from the guide with the chosen scope flag.

---

Category 4: Hooks

Detect: Check detection.global.settings_json.has_hooks and detection.global.hooks_dir

AskUserQuestion (multiSelect: true) — which hooks to configure:

• Block secrets hook — PreToolUse hook that blocks Read/Edit/Write access to .env, secrets.json, id_rsa, and similar files
• Setup hook — Runs npm install && npm run prepare on session init
• Custom hook — Describe your hook (text input)

Block Secrets Hook Setup

1. Create ~/.claude/hooks/ directory if missing 2. Write ~/.claude/hooks/block-secrets.py with the block-secrets script from Guide Section 7 3. Read existing ~/.claude/settings.json (or start with {}) 4. Deep-merge the PreToolUse hook configuration:

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Read|Edit|Write",
           "hooks": [{
             "type": "command",
             "command": "python3 ~/.claude/hooks/block-secrets.py"
           }]
         }
       ]
     }
   }

5. Write merged settings back

Setup Hook

Merge into settings.json:

{
  "hooks": {
    "Setup": [{
      "type": "command",
      "command": "npm install && npm run prepare"
    }]
  }
}

---

Category 5: Custom Agents

Detect: Check detection.global.agents_dir and list existing agent files.

AskUserQuestion (multiSelect: true) — create starter agents:

• Code reviewer — Read-only agent (Read, Grep, Glob) using Sonnet for code review
• Security auditor — Read-only agent (Read, Grep, Glob) using Opus for security analysis
• Documentation writer — Read-write agent (Read, Write, Grep, Glob) using Sonnet for docs

AskUserQuestion — agent scope:

• Personal (~/.claude/agents/) — available in all projects
• Project (.claude/agents/) — this project only

Execute: Create agent .md files with appropriate frontmatter and system prompts.

Agent Templates

code-reviewer.md:

---
name: code-reviewer
description: Reviews code for security, performance, and best practices. Use for code review tasks.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. When reviewing code:
1. Check for security vulnerabilities (OWASP Top 10)
2. Look for performance issues (N+1 queries, memory leaks)
3. Verify error handling (edge cases, null checks)
4. Assess code maintainability and naming
5. Provide specific line references and concrete fixes

Be critical but constructive. Explain WHY something is a problem.

security-auditor.md:

---
name: security-auditor
description: Audits code for security vulnerabilities, secrets exposure, and compliance issues.
tools: Read, Grep, Glob
model: opus
---

You are a security auditor. When auditing code:
1. Scan for hardcoded secrets, API keys, and credentials
2. Check for injection vulnerabilities (SQL, XSS, command injection)
3. Verify authentication and authorization patterns
4. Review dependency versions for known CVEs
5. Check file permissions and access controls

Report findings with severity ratings (Critical/High/Medium/Low).

documentation-writer.md:

---
name: documentation-writer
description: Writes and updates project documentation, READMEs, and code comments.
tools: Read, Write, Grep, Glob
model: sonnet
---

You are a technical documentation writer. When writing docs:
1. Start with a clear overview of what the component does
2. Include usage examples with realistic code
3. Document parameters, return values, and error cases
4. Add architecture notes for complex components
5. Keep language concise and scannable

Match the existing documentation style in the project.

---

Category 6: Keybindings

Detect: Check detection.global.keybindings_json.exists

If exists: Read the file, show current bindings, offer to add more.

AskUserQuestion (multiSelect: true) — recommended keybindings from the guide:

• ctrl+shift+r -> /review (code review)
• ctrl+shift+d -> /deploy (deploy)
• ctrl+shift+t -> /test (run tests)
• ctrl+shift+c -> /commit (create commit)

Execute: Create or merge ~/.claude/keybindings.json.

---

Category 7: Settings

Detect: Check detection.global.settings_json

AskUserQuestion — language preference:

• English (default)
• Other (text input for language code, e.g., "ja", "es", "pt")

AskUserQuestion — background tasks:

• Enable (recommended)
• Disable

Execute: Read existing ~/.claude/settings.json, merge new settings, write back.

---

Confirmation Summary

Before executing any changes, show a summary table:

## Proposed Changes

| Action | Target | Description |
|--------|--------|-------------|
| CREATE | ~/.claude/CLAUDE.md | Global security rules + account config |
| CREATE | .claude/agents/ | Project agent directory |
| INSTALL | Context7 MCP | claude mcp add context7 (global) |
| SKIP | .gitignore | Already exists |
| ... | ... | ... |

Total: X files to create, Y servers to install, Z settings to update.

Use AskUserQuestion:

• Proceed with all changes
• Modify selections (go back to category selection)
• Cancel

---

Post-Setup Summary

After execution, show:

## Setup Complete

| Status | Item |
|--------|------|
| [done] | Global CLAUDE.md with 3 security rules |
| [done] | Project scaffolding (5 directories, 3 files) |
| [done] | 3 MCP servers installed (Context7, Filesystem, Sequential Thinking) |
| [done] | Block-secrets hook configured |
| [skip] | Custom agents (skipped by user) |
| [done] | 4 keybindings configured |
| [done] | Language set to English |

## Next Steps
- Run `/context` to check your token usage
- Try `ctrl+shift+r` to trigger code review
- Run `/devtools:code-env-setup` again anytime to add more configuration