---
name: local-environment-check
description: Verify local development environment is correctly configured. Use when (1) Setting up a new development machine, (2) Debugging environment issues, (3) Onboarding new team members, (4) Verifying tool versions, (5) Checking port availability.
---

# Local Environment Check

## Purpose

Verify that the local development environment has all required tools, correct versions, and proper configuration before starting work.

## Checks to Perform

### 1. Required Tools
```bash
# Check Node.js
node --version    # Expected: v18+ or v20+

# Check npm/bun/pnpm
npm --version     # Expected: 9+
bun --version     # If using bun
pnpm --version    # If using pnpm

# Check Python (if applicable)
python3 --version # Expected: 3.10+
pip --version

# Check Git
git --version     # Expected: 2.30+

# Check GitHub CLI
gh --version
gh auth status    # Verify authenticated
```

### 2. Environment Variables
```bash
# Check required env vars are set
env | grep -E "^(NODE_ENV|API_URL|DATABASE_URL)" || echo "Missing env vars"

# Check .env file exists
[ -f .env ] && echo ".env exists" || echo "WARNING: No .env file"
```

### 3. Port Availability
```bash
# Check if common dev ports are free
lsof -i :3000 2>/dev/null && echo "Port 3000 in use" || echo "Port 3000 available"
lsof -i :5432 2>/dev/null && echo "Port 5432 in use" || echo "Port 5432 available"
lsof -i :8080 2>/dev/null && echo "Port 8080 in use" || echo "Port 8080 available"
```

### 4. Dependencies
```bash
# Install and verify dependencies
npm install       # or bun install / pnpm install
npm run build     # Verify build works
npm test          # Verify tests pass
```

### 5. Git Configuration
```bash
# Verify git hooks are installed
ls -la .git/hooks/pre-commit .git/hooks/commit-msg 2>/dev/null

# If missing, install them
bash .claude/hooks/install-hooks.sh
```

## Troubleshooting

| Issue | Solution |
|-------|---------|
| Node version too old | Use `nvm install 20` |
| Port already in use | Kill process: `kill $(lsof -t -i:3000)` |
| Missing env vars | Copy from `.env.example`: `cp .env.example .env` |
| Git hooks not installed | Run `bash .claude/hooks/install-hooks.sh` |
| npm install fails | Delete `node_modules` and `package-lock.json`, retry |
