macOS Development Environment

Complete, automated development environment setup for macOS with intelligent syncing and error recovery

---

🚀 Quick Start

One command to set up everything:

git clone git@github.com:omarmun0z/dev-environment.git ~/dev-environment
cd ~/dev-environment
./install.sh

That's it! The installer will:

• ✅ Auto-install all development tools
• ✅ Install Claude Code CLI early (Step 2)
• ✅ Install Homebrew packages (codex, gemini-cli, gh, and more)
• ✅ Install Node.js LTS via nvm
• ✅ Auto-install essential VS Code extensions
• ✅ Configure shell and terminal with MCP servers
• ✅ Auto-fix common issues (SSH keys, Xcode tools, network)
• ✅ Handle Intel and Apple Silicon Macs automatically

Estimated time: 15-30 minutes (mostly automated)

---

🆕 What's New (v4.3 - November 2025)

Major Improvements:

🧪 Automated Testing Suite (NEW!)

• Comprehensive test suite - 60+ automated tests covering unit and integration testing
• GitHub Actions CI/CD - Automated testing on every push and pull request
• Regression tests - Ensures previously fixed bugs don't reoccur
• Test runner - Simple ./tests/test_runner.sh to run all tests
• See Testing section below

🔄 Auto-Update System (Sprint 1)

• Smart update script - make update or ./update.sh for intelligent environment updates
• Git post-merge hook - Automatically notifies you of important changes after git pull
• Automatic config updates - Shell and terminal configs update immediately via symlinks
• Package change detection - Detects and prompts for new package installations
• See Update Your Installation section below

🚀 Optimized Installation Flow (14 Steps)

• Claude Code now installs early (Step 2) - Available immediately for troubleshooting
• GitHub CLI authentication added as Step 4 - Automated gh auth login
• Streamlined tool installation - Better error messages and progress tracking

📦 Package Management Improvements

• Codex & Gemini via Homebrew - Moved from npm to Homebrew for stability
  • brew install codex and brew install gemini-cli
  • System-wide availability without nvm dependencies
• Centralized configuration - All packages defined in config/packages.conf
• NPM packages minimal - Only essential npm-only tools

⚡ Performance Enhancements

• Lazy-loaded nvm - Shell startup improved from ~400ms to ~100ms
• Configurable loading modes - Choose between lazy (default), full, or path-only
• See Performance Optimizations section below

🔧 MCP Server Configuration

• Simplified MCP setup - Uses npx -y codex-mcp-server and npx -y gemini-mcp-tool
• No path resolution needed - Homebrew packages work system-wide
• Better error messages - Clear instructions if setup fails

📚 Documentation Updates

• Complete README overhaul with accurate installation steps
• New CHANGELOG.md and CONTRIBUTING.md files
• Archived completed improvement plans
• Enhanced verification and troubleshooting guides

For full version history, see CHANGELOG.md

---

✨ Key Features

🤖 Intelligent Auto-Fix

• Automatically installs missing Xcode Command Line Tools
• Auto-generates SSH keys if needed
• Falls back to HTTPS if SSH fails
• Retries network operations with exponential backoff
• Verifies prerequisites before starting

📦 Complete Tool Stack

• Ghostty (modern GPU-accelerated terminal)
• Docker Desktop (containerization)
• Visual Studio Code (editor)
• Essential VS Code extensions (12 total: Python suite, Docker/Containers, Makefile, GitLens, Copilot suite, Prettier, ESLint)
• Claude Code CLI (AI pair programmer, installed early)
• Codex & Gemini CLI tools via Homebrew (AI assistants with MCP integration)
• PostgreSQL 17 (database)
• Python 3.13 (programming)
• Node.js LTS via nvm (JavaScript runtime)
• GitHub CLI with authentication, ripgrep, and 30+ more tools

🎯 Cross-Platform

• Works on Apple Silicon (M1/M2/M3/M4)
• Works on Intel Macs
• Automatically detects architecture
• Portable across different usernames and paths

---

📋 What Gets Installed

Development Tools

Tool	Version	Purpose
Ghostty	Latest	Modern GPU-accelerated terminal
Docker Desktop	Latest	Containerization
VS Code	Latest	Code editor
Claude Code	Latest	AI pair programmer (installed Step 2)
Codex CLI	Latest (Homebrew)	OpenAI Codex CLI for AI coding
Gemini CLI	Latest (Homebrew)	Google Gemini API CLI
GitHub CLI (gh)	Latest (Homebrew)	GitHub integration and authentication
PostgreSQL	17	Database server
Python	3.13	Programming language
Node.js	LTS (nvm)	JavaScript runtime
ripgrep	Latest	Fast search tool

Plus: 30+ supporting packages and libraries

Editor Boost: 12 essential VS Code extensions are installed automatically:

• Python Suite: ms-python.python, vscode-pylance, debugpy, vscode-python-envs
• Containers: vscode-docker, vscode-containers
• Development: makefile-tools, GitLens, Copilot, Copilot Chat
• Code Quality: Prettier, ESLint

Configuration Files

• zshrc: Shell configuration with PATH optimization and custom aliases
• zprofile: Login shell bootstrap (Homebrew handled in zshrc)
• ghostty/config: Ghostty terminal configuration with QoL improvements (auto-themes, ligatures, etc.)
  • 📖 Ghostty Keyboard Shortcuts & Features Guide - Complete cheatsheet for Ghostty terminal

MCP-First Architecture: Multi-Agent AI System

This environment implements an MCP-First Architecture using the Model Context Protocol to create a collaborative multi-agent AI system. Instead of relying on a single AI assistant, you get three specialized agents working together through Claude Code.

🎭 The Three-Agent System

1. Claude Code (The Orchestrator)

• Role: Primary interface and task coordinator
• Strengths: File editing, git operations, terminal commands, project management
• When to use: General coding tasks, refactoring, debugging, git workflows

2. Gemini Pro (The Analyst)

• Role: Deep codebase analysis and research
• Strengths: 1M-token context window, pattern recognition, architecture analysis
• When to use: "Understand this entire codebase", "Find all instances of X pattern", "Analyze dependencies"

3. OpenAI Codex (The Specialist)

• Role: Expert code generation
• Strengths: Algorithm implementation, complex logic, language-specific patterns
• When to use: "Write an optimized sorting algorithm", "Generate API client code", "Implement design pattern"

🔄 How It Works

The Model Context Protocol (MCP) enables seamless communication between these agents:

┌─────────────────┐
│   Claude Code   │ ← Your primary interface
│ (Orchestrator)  │
└────────┬────────┘
         │
         ├─────────> MCP Protocol
         │
    ┌────┴────┬──────────┐
    │         │          │
┌───▼────┐ ┌─▼──────┐ ┌─▼──────┐
│ Gemini │ │ Codex  │ │ Future │
│  (The  │ │  (The  │ │ Agents │
│Analyst)│ │Special)│ │        │
└────────┘ └────────┘ └────────┘

🗣️ Natural Language Delegation

Claude Code automatically delegates tasks to the right agent based on your natural language request:

Examples:

You: "Use gemini to analyze the entire authentication system"
→ Claude Code invokes Gemini with large context window

You: "Ask codex to write a binary search tree implementation"
→ Claude Code delegates to Codex for expert code generation

You: "Check if there are any security vulnerabilities"
→ Claude Code coordinates: Gemini analyzes, Codex suggests fixes

🛠️ Manual Tool Invocation

You can explicitly call MCP tools when you want direct control:

List Available MCP Servers:

claude mcp list

Check Server Status:

claude mcp get codex
claude mcp get gemini-cli

Verify MCP Configuration:

# View MCP configuration file
cat ~/.claude.json

# Test codex CLI directly
codex --help

# Test gemini CLI directly
gemini --help

📋 Common Workflows

Workflow 1: Codebase Analysis + Refactoring

1. "Use gemini to analyze the entire API module structure"
   → Gemini reads and analyzes with 1M token context

2. "Based on that analysis, refactor the authentication handlers"
   → Claude Code implements the refactoring

3. "Ask codex to optimize the token validation algorithm"
   → Codex provides expert implementation

Workflow 2: Feature Implementation

1. "Use gemini to find all database query patterns in the codebase"
   → Gemini searches and identifies patterns

2. "Ask codex to write a query builder class following those patterns"
   → Codex generates consistent implementation

3. "Integrate the new query builder into the existing code"
   → Claude Code handles file edits and integration

Workflow 3: Bug Investigation

1. "Use gemini to trace where user authentication is handled"
   → Gemini analyzes auth flow across entire codebase

2. "Find the bug causing failed logins"
   → Claude Code debugs specific issue

3. "Ask codex to write comprehensive tests for the auth system"
   → Codex generates test suite

⚙️ MCP Server Configuration

Both MCP servers are automatically configured during installation:

Codex MCP Server:

Command: npx -y codex-mcp-server
Type: stdio
Authentication: ChatGPT Plus account (oauth)
Installation: Homebrew formula "codex"

Gemini MCP Server:

Command: npx -y gemini-mcp-tool
Type: stdio
Authentication: Google AI Studio API key
Installation: Homebrew formula "gemini-cli"

🔐 Authentication Setup

Codex (requires ChatGPT Plus):

codex login
# Opens browser for ChatGPT OAuth authentication

Gemini (requires Google AI Studio API key):

gemini config
# Enter API key from: https://aistudio.google.com/apikey

✅ Verifying Your Setup

After installation, verify everything is working:

# Check MCP servers are configured
claude mcp list

# Verify codex authentication
codex whoami

# Verify gemini authentication
gemini config

# Test in Claude Code
# Open Claude Code and try: "Use gemini to list all files in this project"

Expected Output:

$ claude mcp list
codex       ✓ Ready
gemini-cli  ✓ Ready

🎯 Best Practices

When to use each agent:

• Claude Code: Your default for all general tasks, file operations, and coordination
• Gemini: Large-scale analysis, finding patterns across many files, research
• Codex: Complex algorithms, language-specific implementations, expert code generation

Tips:

• Start with Claude Code for most tasks - it will delegate when beneficial
• Use explicit "Use gemini..." or "Ask codex..." when you want a specific agent
• Gemini excels at "find all", "analyze entire", "trace through" type requests
• Codex shines for "implement", "optimize", "generate" type requests

📚 Learn More

• Model Context Protocol Documentation
• Claude Code MCP Guide
• Gemini API Documentation
• OpenAI Codex Documentation

⚡ Performance Optimizations

Shell Startup Time

The repository uses lazy loading for nvm to minimize shell startup time:

• Without optimization: ~400ms
• With lazy loading: ~100ms (default)
• First command delay: ~150ms (one-time per session)

How It Works

Node.js binaries are added to PATH immediately for fast access, but nvm itself only loads when you run nvm, node, npm, or npx for the first time in a shell session.

Changing the Loading Strategy

Edit .zshrc and set the NVM_LOADING environment variable before the nvm section:

# Add to top of .zshrc or set in your environment
export NVM_LOADING="lazy"  # or "full" or "path-only"

Options:

• lazy (default): Load nvm on first use — faster startup (~100ms), slight delay on first command
• full: Load nvm immediately — slower startup (~400ms), instant nvm commands
• path-only: Only add node to PATH — fastest startup (~50ms), no nvm commands available

Benchmarking Your Setup

# Measure your shell startup time (run 10 times and average)
for i in {1..10}; do /usr/bin/time -p zsh -i -c exit 2>&1 | grep real; done | awk '{sum+=$2; count++} END {print "Average:", sum/count, "seconds"}'

---

🎯 Installation Steps

Step 1: Clone Repository

git clone git@github.com:omarmun0z/dev-environment.git ~/dev-environment
cd ~/dev-environment

Step 2: Run Installer

./install.sh

Step 3: Follow Prompts

The installer will guide you through:

1. Homebrew installation (if needed)
2. Claude Code CLI installation (installed early for immediate availability)
3. Homebrew package installation (28+ formulae including codex, gemini-cli, gh)
4. GitHub CLI authentication (gh auth login)
5. nvm installation (via official script) & Node.js setup (LTS install & default alias)
6. NPM global packages (minimal - most tools via Homebrew now)
7. Application installation (4 casks: Docker, VS Code, Ghostty)
8. VS Code extensions (auto-install 12 essential extensions)
9. Shell configuration (automatic symlink setup)
10. Service startup (PostgreSQL auto-start)
11. Docker Desktop launch (background startup)
12. MCP server configuration (Codex & Gemini with npx)
13. Verification (comprehensive tool check)

Step 4: Restart Terminal

# Close and reopen Terminal.app
# All configurations will be loaded

---

🔧 Auto-Fix Capabilities

The installer automatically fixes common issues:

✅ Missing Xcode Command Line Tools

⚠ Xcode Command Line Tools not found
ℹ Installing automatically...
✓ Installed and verified

✅ No SSH Keys

⚠ No SSH key found for GitHub
ℹ Generating SSH key automatically...
✓ SSH key generated at ~/.ssh/id_ed25519
[Displays key with GitHub setup instructions]

✅ SSH Clone Failures

⚠ SSH clone failed. Checking configuration...
ℹ Attempting to set up SSH...
[Auto-generates keys if needed]
ℹ Falling back to HTTPS clone...
✓ Repository cloned via HTTPS

✅ Network Timeouts

⚠ Attempt 1 failed, retrying in 2s...
⚠ Attempt 2 failed, retrying in 4s...
✓ Operation successful

---

🔧 Configuration

All package selections live in config/packages.conf. The file defines three Bash arrays (FORMULAE, CASKS, and VSCODE_EXTENSIONS) that both install.sh and uninstall.sh source at runtime.

• Add a new package by appending a quoted entry with an inline comment explaining its purpose.
• Remove or skip a package by commenting out the corresponding line.
• Keep the category comments in the file to maintain readability and help future contributors understand the grouping.
• Follow the same quoting and indentation style so new entries are easy to scan.

Example: To add the Yarn package manager and skip Docker Desktop:

    "yarn"              # JavaScript package manager for monorepos
#   "docker-desktop"    # Commented out during CI runs

Whenever you modify packages.conf, rerun ./install.sh or ./uninstall.sh to apply the updated selections automatically.

🔒 Local Configuration Overrides

For per-machine customization without modifying tracked files, use packages.local.conf:

# 1. Copy the example file
cp config/packages.local.conf.example config/packages.local.conf

# 2. Edit with your custom packages
nano config/packages.local.conf

# 3. Run installer - it will use your overrides
./install.sh --dry-run  # Preview your custom configuration
./install.sh            # Install with your overrides

What you can do with packages.local.conf:

• Add packages specific to your machine:

  LOCAL_FORMULAE=("go" "rustup" "terraform")
  LOCAL_CASKS=("slack" "zoom" "spotify")

• Exclude default packages you don't need:

  EXCLUDE_FORMULAE=("postgresql@17")
  EXCLUDE_CASKS=("docker-desktop")

• Environment-specific setups:

  # Work Mac
  LOCAL_CASKS=("slack" "zoom" "microsoft-teams")
  EXCLUDE_CASKS=("spotify" "discord")
  
  # Personal Mac
  LOCAL_CASKS=("spotify" "discord" "steam")

Benefits:

• ✅ packages.local.conf is gitignored (won't be committed)
• ✅ Your customizations survive git pull updates
• ✅ Different configurations for work vs personal machines
• ✅ Easy to share base config while keeping local tweaks private

Version Pinning:

Homebrew supports version-specific formulae for many packages:

LOCAL_FORMULAE=(
    "python@3.13"      # Specific Python version
    "postgresql@17"    # Specific PostgreSQL version
    "node@20"          # Node.js 20.x
    "ruby@3.2"         # Ruby 3.2.x
)

Use brew search <package> to see available versions.

---

📚 Additional Documentation

• Pre-Installation Checklist - Complete setup guide and prerequisites
• CHANGELOG.md - Version history and release notes
• CONTRIBUTING.md - Guidelines for contributing code and documentation
• Ghostty Shortcuts Cheatsheet - Complete keyboard shortcuts and features
• Configuration Guide - How to customize package selection

---

🛠 Troubleshooting

Installation Issues

Homebrew fails to install:

• Check internet connection
• Ensure macOS 11+ (Big Sur or later)
• Run: xcode-select --install

SSH clone fails:

• Installer will auto-generate SSH keys
• Add key to GitHub: https://github.com/settings/keys
• Or use HTTPS (automatic fallback)

Package installation fails:

• Installer retries automatically (3 attempts)
• Check network connectivity
• View detailed errors in terminal

Post-Installation

Commands not found after restart:

• Ensure you restarted Terminal.app
• Check: echo $PATH
• Re-run: ~/dev-environment/setup.sh

Docker not starting:

• Open Docker.app from Applications
• Check menu bar for Docker icon
• Wait 1-2 minutes for startup

PostgreSQL not running:

• Run: brew services start postgresql@17
• Check: brew services list

nvm installation:

• nvm is installed using the official installation script (not via Homebrew)
• The installer automatically installs nvm if not already present
• Manual installation: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
• This is the recommended method from the nvm project maintainers

---

🔄 Updating Your Setup

Pull Latest Changes

cd ~/dev-environment
git pull

Re-run Setup (Non-Destructive)

cd ~/dev-environment
./setup.sh

Verify Your Installation

cd ~/dev-environment

# Quick verification (read-only)
./verify-setup.sh

# Deep verification with all checks
./verify-setup.sh --deep

# Fix issues automatically
./verify-setup.sh --fix

# Generate detailed report for troubleshooting
./verify-setup.sh --deep --report

This verification script checks:

• ✓ Symlink status
• ✓ Package configuration
• ✓ nvm lazy loading
• ✓ MCP server configuration
• ✓ Repository version
• ✓ Service status (PostgreSQL, Docker)
• ✓ Tool availability and versions

New: Use --report flag to generate a comprehensive verification report file with full system information, perfect for sharing when requesting support.

Benchmark Performance

cd ~/dev-environment

# Run all performance benchmarks
./benchmark.sh

# Specific benchmarks
./benchmark.sh --shell       # Shell startup time only
./benchmark.sh --nvm         # nvm loading performance
./benchmark.sh --brew        # Homebrew operations

# Or via Makefile
make benchmark

Performance targets:

• Shell startup: ~100ms (with lazy loading)
• Installation time: ~20-25 minutes
• Package checks: 30x faster with caching

New: Use ./benchmark.sh to measure and track performance metrics over time.

Testing

Run the automated test suite to ensure everything works correctly:

cd ~/dev-environment

# Run all tests
./tests/test_runner.sh

# Run unit tests only
./tests/test_runner.sh --unit

# Run integration tests only
./tests/test_runner.sh --integration

# Verbose output
./tests/test_runner.sh --verbose

Test Coverage:

• 60+ automated tests covering:
  • Unit tests: Helper functions, syntax validation, package parsing
  • Integration tests: Update script, verification, git hooks
  • Regression tests: Previously fixed bugs

CI/CD: Tests run automatically on:

• Every push to the repository
• Every pull request
• Manual workflow dispatch

See .github/workflows/test.yml for CI/CD configuration.

Writing Tests: See tests/README.md for:

• Test structure and organization
• Assertion functions available
• Templates for new tests
• Testing best practices

New: Comprehensive test suite ensures quality and prevents regressions!

Update Your Installation

Keep your development environment up to date with the latest improvements:

cd ~/dev-environment

# Smart update (recommended)
make update              # Interactive: prompts for important changes
./update.sh              # Same as make update

# Auto update (no prompts)
./update.sh --auto       # Automatically applies all updates

# Preview update
./update.sh --dry-run    # See what would change without making changes

What happens during update:

1. ✅ Pulls latest changes from repository
2. ✅ Detects changes to package configuration
3. ✅ Prompts to install new packages (if needed)
4. ✅ Runs verification to check system state
5. ✅ Reports status and suggests next steps

Auto-update features:

• Symlinked configs update automatically: Shell configs (~/.zshrc, ~/.zprofile) and terminal configs (Ghostty) update immediately when you pull changes
• Git post-merge hook: Automatically runs after git pull to notify you of important changes
• Smart package detection: Detects when config/packages.conf changes and prompts to update

Example workflow:

# Pull latest changes (hook runs automatically)
cd ~/dev-environment
git pull

# The post-merge hook will:
# - Notify you of changes
# - Run verification
# - Suggest next steps

# Or use the update script for full control
make update

Restart your shell after updates:

exec zsh    # Reload shell configuration

New in Sprint 1: Automatic environment updates via git hooks and smart update script!

Uninstall

cd ~/dev-environment
make uninstall  # or ./uninstall.sh

Clean Slate (For Re-installation)

If you previously installed an old version and want to ensure complete cleanup before reinstalling:

# Download and run the clean slate script
curl -fsSL https://raw.githubusercontent.com/omarmun0z/dev-environment/main/clean-slate.sh | bash

# Or if you have the repo:
cd ~/dev-environment
./clean-slate.sh

This script will:

• Remove all symlinks pointing to dev-environment
• Find and remove backup directories
• Clear MCP server configurations
• Check for manual config file modifications
• Prepare for fresh installation

---

🏗 Repository Structure

dev-environment/
├── README.md                      # This file
├── PRE-INSTALLATION-CHECKLIST.md  # Pre-install guide
├── IMPROVEMENT-PLAN.md            # Implementation roadmap
├── config/
│   ├── README.md                  # Package configuration guide
│   └── packages.conf              # Shared package definitions for scripts
├── install.sh                     # Main installation script
├── setup.sh                       # Configuration setup
├── uninstall.sh                   # Automated uninstall
├── verify-setup.sh                # Verify installation status
├── clean-slate.sh                 # Complete cleanup for re-installation
├── Makefile                       # Build automation
├── ghostty/
│   └── config                     # Ghostty terminal configuration
├── zshrc                          # Shell configuration
└── zprofile                       # Login shell bootstrap

---

🎯 Design Principles

Automation First

• One command installation
• Auto-fix common issues
• Minimal user intervention

Portability

• Works on Intel and Apple Silicon
• No hard-coded paths or usernames
• Cross-device compatible

Safety

• Creates backups before changes
• Validates all operations
• Clear error messages

Intelligence

• Retries failed operations
• Falls back to alternatives
• Merges data intelligently

---

🔐 Security

Private Repository

This repository is private for personal use only.

SSH Keys

• Auto-generated during setup
• Stored in ~/.ssh/id_ed25519
• Added to ssh-agent automatically
• Configured in ~/.ssh/config

No Secrets in Code

• No API keys stored
• No passwords committed
• Credentials stored separately

---

📊 Comparison

Before This Setup

# Manual installation of each tool
brew install docker
brew install postgresql
brew install python
# ... 20+ more tools

# Manual configuration
cp config files...
edit ~/.zshrc
source ~/.zshrc

Time: 2-3 hours of manual work

With This Setup

git clone git@github.com:omarmun0z/dev-environment.git ~/dev-environment
cd ~/dev-environment
./install.sh

Time: 15-30 minutes (mostly automated)

---

🤝 Contributing

This is a private repository for personal use. For questions or issues:

1. Check troubleshooting section
2. Review documentation in subdirectories
3. Test changes before committing

---

📜 License

Private repository - for personal use only.

---

📅 Version History

• v4.2 (2025-11-04) - Early Claude Code install, Homebrew packages, documentation overhaul
• v4.1 (2025-11-03) - MCP server configuration, centralized config, nvm lazy loading
• v4.0 (2025-11-01) - Ghostty terminal, single-device optimization
• v3.0 (2025-10-31) - Intelligent merging, convenience scripts
• v2.0 (2025-10-31) - Auto-fix system, error handling
• v1.0 (2025-10-31) - Initial automated installation

For detailed changelog, see CHANGELOG.md

---

Ready to get started?

git clone git@github.com:omarmun0z/dev-environment.git ~/dev-environment
cd ~/dev-environment
./install.sh

🎉 Your complete development environment will be ready in 15-30 minutes!