@nhangen/universal-dev-env

Universal Development Environment

🚀 One-click setup for modern development environments with AI tools, cloud CLIs, and optimized containers

🔗 Live Distribution Channels

• 📦 NPM Package: https://www.npmjs.com/package/@nhangen/universal-dev-env
• 🔧 VS Code Extension: Coming soon to marketplace
• 🐙 GitHub Repository: https://github.com/nhangen/universal-dev-env
• ⚡ One-Line Installer: curl -fsSL https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install.sh | bash (Unix/Linux/macOS)

🌟 Features

• 🤖 AI-Powered Development: Pre-configured Claude and Gemini CLI tools
• ☁️ Cloud-Ready: Google Cloud CLI, GitHub CLI, and deployment configs
• 🐳 Container Optimized: Multi-stage Docker builds with security best practices
• 🔧 VS Code Integration: Rich extension pack and DevContainer support
• 🌍 Universal Compatibility: Works on Alpine, Debian, macOS, Windows, and WSL
• ⚡ Lightning Fast: Optimized build processes and intelligent caching
• 💾 Smart Caching: Automatic caching of downloads and installations for faster setup

🚀 Quick Start

One-Line Install

Unix/Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install.sh | bash

Windows (PowerShell as Administrator):

iwr -useb https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install-windows.bat | iex

Windows (Alternative - Download & Run):

# Download and run the batch installer
curl -O https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install-windows.bat
# Right-click install-windows.bat and "Run as Administrator"

Package Manager Install

Cross-Platform (npm):

npm install -g @nhangen/universal-dev-env

macOS (Homebrew):

brew tap nhangen/universal-dev-env
brew install universal-dev-env

Windows (Chocolatey):

# Coming soon - use npm method above for now
choco install universal-dev-env

VS Code Extension

# Coming soon to VS Code Marketplace
# For now, use the npm package method above

⚡ Quick Troubleshooting

Setup failed? → Jump to Troubleshooting Guide

Common fixes:

• macOS "Unsupported OS": curl -fsSL https://raw.githubusercontent.com/nhangen/universal-dev-env/main/universal-setup.sh -o universal-setup.sh && chmod +x universal-setup.sh && ./universal-setup.sh
• Permission denied: chmod +x universal-setup.sh
• Clear cache: uds cache --clear
• Start fresh: rm -rf project-name && uds init --no-cache

📋 Usage

Initialize New Project

# Create new project directory
mkdir my-awesome-project
cd my-awesome-project
uds init

# OR initialize in current directory (no subdirectory created)
cd my-existing-directory
uds init --here

# OR initialize Python ML project with one command
uds init --type python --ml --here

Setup Existing Project

cd existing-project
uds setup

Available Commands

uds init                    # Initialize project with dev environment
uds init --here             # Initialize in current directory (no subdirectory)
uds init --type python --ml # Initialize Python project with ML libraries
uds init --ai-context       # Initialize with AI context file for Claude/Gemini/Copilot
uds init --no-cache         # Initialize without caching (fresh downloads)
uds setup                   # Install development tools in existing project
uds update                  # Update to latest version
uds uninstall               # Completely remove Universal Dev Environment
uds cache --info            # Show cache information
uds cache --clear           # Clear cached files
universal-dev-setup         # Main setup script (direct)

# AI Agent Configuration
uds-ai-setup configure      # 🤖 Configure AI agent roles for Claude/Gemini
uds-ai-setup role-info      # Show available agent roles
uds-ai-setup add-role       # Add custom AI agent role
uds-ai-setup generate-handoff --role <role> # Generate session handoff

🛠️ What Gets Installed

Core Development Tools

• Node.js & npm - JavaScript runtime and package manager
• Python 3 & pip - Python runtime and package manager
• Conda/Miniconda - Python environment management (macOS)
• Git - Version control system
• Docker - Container platform (optional on Windows)
• VS Code - Code editor (Windows only, manual on other platforms)

AI & Cloud CLI Tools

• Claude CLI (claude) - AI-powered coding assistant
• Gemini CLI (gemini) - Google's AI development tool
• GitHub CLI (gh) - GitHub integration and automation
• Google Cloud CLI (gcloud) - Cloud deployment and management

Package Managers (Auto-installed if missing)

• macOS: Homebrew (brew)
• Windows: Chocolatey (choco)
• Linux: Uses system package manager (apt, yum, apk)

Container Features

• Multi-stage Docker builds for optimal image sizes
• Security-hardened containers with non-root users
• Alpine and Debian base image options
• Playwright browser automation support
• Health checks and proper signal handling

VS Code Extensions

• TypeScript/JavaScript development
• React and Node.js tooling
• Docker and Kubernetes support
• AI coding assistants (GitHub Copilot)
• Cloud development tools
• Linting, formatting, and debugging

🏗️ Project Types Supported

React Frontend

uds init --type react

• Frontend Only: Pure React frontend without backend
• Express Backend: React + Express.js API server
• Next.js Full-stack: Next.js with built-in API routes
• Firebase Functions: React + Firebase serverless functions
• Serverless: React + Vercel/Netlify Edge functions

Choose backend during setup or use flags:

uds init --type react --backend express    # React + Express
uds init --type react --backend nextjs     # Next.js full-stack
uds init --type react --backend firebase   # React + Firebase
uds init --type react --backend serverless # React + Vercel/Netlify
uds init --type react --backend none       # Frontend only

# Add AI context for shared memory between Claude/Gemini/Copilot
uds init --type react --ai-context         # Generates .ai/ folder

Node.js Backend

uds init --type node

• Express.js server setup
• Development with nodemon
• Production PM2 configuration
• Database integration helpers

Full-Stack Applications

uds init --type full-stack

• React frontend + Node.js backend
• Concurrent development servers
• Shared TypeScript types
• Docker Compose orchestration

Python Applications

uds init --type python

• Complete Python project structure with main.py
• Optional ML Libraries: Prompted to install NumPy, Pandas, Scikit-learn, Jupyter, etc.
• Smart ML Setup: Conda installs ML libraries for better performance
• Automatic conda environment creation (if conda available)
• Virtual environment setup (fallback)
• requirements.txt with ML or standard packages
• .env file for environment variables
• Python-specific .gitignore
• activate_env.sh script for easy activation
• ML starter code with sample dataset and basic workflow

🤖 AI Agent Setup & Collaboration

AI Agent Role Configuration

Configure AI agent roles for your project to enable structured collaboration between Claude, Gemini, and other AI assistants:

# Interactive setup - configure which roles are available
uds-ai-setup configure

# View configured roles
uds-ai-setup role-info

# Add custom role for project-specific needs
uds-ai-setup add-role

Available AI Agent Roles:

• 👨‍💻 Senior Software Engineer: Code quality, architecture, testing
• 📊 Senior Data Scientist: ML/AI research, data analysis, experiments
• ⚙️ DevOps Engineer: Infrastructure, CI/CD, deployment
• 🔒 Cybersecurity Analyst: Security assessment, vulnerability analysis
• 🧠 AI Research Scientist: Model development, research documentation
• 📋 Project Manager: Task tracking, coordination, milestones
• 📝 Technical Writer: Documentation, guides, API docs
• 🧪 QA Engineer: Testing, quality assurance, automation
• 🗄️ Database Administrator: Data management, optimization
• ⚛️ Quantum Specialist: Quantum computing, specialized algorithms

Session Handoff System

Enable seamless agent-to-agent collaboration:

# Generate handoff when ending your session
uds-ai-setup generate-handoff --role your-role --session-summary "what you accomplished"

Generated Files:

• AI_AGENT_ONBOARDING.md - Instructions for new AI agents
• .ai-agent-config.json - Role configuration and project context
• SESSION_HANDOFF.md - Current session status and next steps

🧠 AI Context & Shared Memory

Universal Dev Environment can generate a comprehensive .ai/ folder that provides shared context between Claude, Gemini, and GitHub Copilot.

Enable AI Context

uds init --ai-context                    # Generate .ai/ folder with context files
uds init --type python --ml --ai-context # ML project with AI context

What the .ai/ Folder Provides:

📁 .ai/ Folder Structure:

.ai/
├── context.md           # Project overview and architecture
├── recent-work.md       # Development sessions and progress  
└── preferences.md       # Coding patterns and project preferences

📋 context.md - Core project information:

• Project overview, tech stack, container strategy
• Quick start prompts for AI conversations
• Technical setup, file structure, development commands
• AI tool persistence instructions

📅 recent-work.md - Development tracking:

• Recent development sessions and completed work
• Current focus and next steps
• Development log template for ongoing updates

🎨 preferences.md - Coding standards:

• Code style preferences and patterns
• Language-specific examples and best practices
• File organization and naming conventions
• Development workflow and deployment strategy

AI Tool Persistence

Automatic configuration for maintaining settings across container rebuilds:

Claude CLI: ~/.config/claude-code/settings.local.json Gemini CLI: ~/.config/gemini/settings.json and state_snapshot.xml
GitHub Copilot: Automatic persistence via VS Code

Usage Examples

Instead of re-explaining your project:

Before: "This is a React app with Express backend using Docker Compose..."

After: "Based on .ai/context.md, help me implement the user authentication system"

For ongoing development context:

"Check .ai/recent-work.md for what I completed yesterday, then help me continue with the next API endpoint"

For consistent code patterns:

"Following the patterns in .ai/preferences.md, create a new React component for the user dashboard"

DevContainer Integration

When --ai-context is used:

• Volume mounts for Claude/Gemini settings are automatically configured
• AI context files available at /workspace/.ai/
• Container displays persistence status on startup
• Environment variables set: AI_CONTEXT_DIR=/workspace/.ai

🪟 Windows-Specific Setup

Universal Dev Environment now has full Windows support via PowerShell:

Prerequisites

• Windows 10/11 with PowerShell 5.1+ (included by default)
• Administrator privileges (required for installation)
• Internet connection for downloading tools

What Gets Installed on Windows

• Chocolatey - Package manager for Windows
• Node.js & npm - JavaScript runtime and package manager
• Git - Version control system
• Visual Studio Code - Code editor
• GitHub Desktop - Git GUI (optional)
• Docker Desktop - Container platform (optional, can skip with -SkipDocker)
• Windows Terminal - Modern terminal application
• GitHub CLI - Command line interface for GitHub
• Claude CLI - AI-powered development assistant
• Gemini CLI - Google's AI development tool

Windows Installation Options

Option 1: One-line PowerShell (Recommended)

# Run PowerShell as Administrator, then:
iwr -useb https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install-windows.bat | iex

Option 2: Manual Download

# Download the installer
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nhangen/universal-dev-env/main/install-windows.bat" -OutFile "install-windows.bat"
# Right-click and "Run as Administrator"

Option 3: Direct PowerShell Script

# Download and run PowerShell script directly
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nhangen/universal-dev-env/main/universal-setup.ps1" -OutFile "universal-setup.ps1"
powershell -ExecutionPolicy Bypass -File "universal-setup.ps1"

Windows Command Options

# Skip Docker Desktop installation
.\universal-setup.ps1 -SkipDocker

# Skip Chocolatey installation (if you already have it)
.\universal-setup.ps1 -SkipChocolatey

# Show help
.\universal-setup.ps1 -Help

🐳 Docker Usage

Development Container

# Build and run development environment
docker build --target development -t my-dev-env .
docker run -it -p 3000:3000 -v $(pwd):/workspace my-dev-env

Production Container

# Build optimized production image
docker build --target production -t my-app .
docker run -p 3000:3000 my-app

DevContainer (VS Code)

• Open project in VS Code
• Install "Dev Containers" extension
• Click "Reopen in Container"
• Start coding! 🎉

💾 Caching

Universal Dev Environment includes intelligent caching to speed up repeated installations:

Cache Features

• 📦 Download Caching: Template files and binaries cached for 30 days
• 🔄 Automatic Fallback: Falls back to cache if downloads fail
• 🆕 Version-Aware: Automatically updates cache when new versions are released
• 🗂️ Organized Storage: Cache stored in ~/.universal-dev-env/cache
• 🧹 Auto-Cleanup: Removes old version caches automatically
• 📊 Cache Management: Built-in tools to monitor and clear cache

Cache Commands

# Show cache information
uds cache --info

# Clear all cached files
uds cache --clear

# Initialize without using cache
uds init --no-cache

# Install without using cache
uds install --no-cache

Cache Location

# Default cache directory
~/.universal-dev-env/cache/

# Cache expires after 30 days OR on version update
# Automatic cleanup of old versions and failed downloads
# Version-aware cache keys ensure fresh content on updates

🔧 Configuration

Environment Variables

# Playwright configuration
export PLAYWRIGHT_BROWSERS_PATH=/usr/bin
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium

# Development mode
export NODE_ENV=development

Custom Configuration

Create .universal-dev-env.json in your project root:

{
  "projectType": "react",
  "baseImage": "debian",
  "features": {
    "aiTools": true,
    "cloudTools": true,
    "playwright": false,
    "multiStage": true
  },
  "ports": [3000, 3001, 8000],
  "customExtensions": [
    "custom.extension-id"
  ]
}

🏢 Enterprise Features

Security

• Non-root container execution
• Minimal attack surface with Alpine Linux
• Security scanning integration
• Secret management best practices

Scalability

• Multi-stage builds for smaller images
• Kubernetes deployment templates
• Load balancer configurations
• Auto-scaling policies

CI/CD Integration

• GitHub Actions workflows
• GitLab CI templates
• Docker registry automation
• Environment promotion pipelines

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/nhangen/universal-dev-env.git
cd universal-dev-env
npm install
npm run dev

Running Tests

npm test

Building Extension

cd vscode-extension
npm run compile
npm run package

📚 Documentation

• Installation Guide
• Configuration Reference
• Docker Guide
• VS Code Extension
• Troubleshooting
• FAQ

🗺️ Roadmap

• Support for more frameworks (Vue, Svelte, Angular)
• Kubernetes templates and Helm charts
• Integration with more AI tools
• Plugin system for custom tools
• Web UI for configuration
• Team collaboration features

🔄 Troubleshooting & Management

Common Scenarios

🍎 macOS: "Unsupported OS" Error If you get "Unsupported OS" when running ./universal-setup.sh:

# The shell script needs to be updated - download latest version
curl -fsSL https://raw.githubusercontent.com/nhangen/universal-dev-env/main/universal-setup.sh -o universal-setup.sh
chmod +x universal-setup.sh
./universal-setup.sh

🔄 Package Installed but Shell Script Failed If npm install -g @nhangen/universal-dev-env worked but ./universal-setup.sh failed:

# Option 1: Update to latest script
curl -fsSL https://raw.githubusercontent.com/nhangen/universal-dev-env/main/universal-setup.sh -o universal-setup.sh
chmod +x universal-setup.sh
./universal-setup.sh

# Option 2: Use Node.js CLI instead (skip shell script)
uds install  # This will install the development tools via Node.js

Restart/Retry Setup

If setup fails or you want to start fresh:

Option 1: Clear cache and retry

# Clear all cached files and retry
uds cache --clear
uds init --no-cache

Option 2: Manual restart

# Remove project directory and start over
rm -rf your-project-name
mkdir your-project-name
cd your-project-name
uds init

Option 3: Re-run shell script

# If the shell script failed, try again
chmod +x universal-setup.sh
./universal-setup.sh

Uninstall Guide

One-Command Uninstall:

uds uninstall  # Interactive uninstall with options
# OR
uds uninstall --yes  # Skip confirmations

Manual NPM Package Removal:

npm uninstall -g @nhangen/universal-dev-env

Remove Generated Files:

# Remove cache directory
rm -rf ~/.universal-dev-env

# Remove development scripts (optional)
rm -f ~/bin/dev-start

# Remove configuration directories (optional - will lose settings)
rm -rf ~/.config/claude-code
rm -rf ~/.config/gh
rm -rf ~/.config/gemini

Remove Installed Tools (Optional):

macOS:

# Remove via Homebrew (only if you want to completely remove these tools)
brew uninstall gh google-cloud-sdk
brew uninstall --cask docker

Windows:

# Remove via Chocolatey (optional)
choco uninstall github-cli google-cloud-sdk docker-desktop

Linux:

# Remove via package manager (optional)
sudo apt-get remove gh google-cloud-sdk  # Debian/Ubuntu
# or
sudo apk del github-cli  # Alpine

Clean Reset:

# Complete clean slate (removes all traces)
npm uninstall -g @nhangen/universal-dev-env
rm -rf ~/.universal-dev-env
rm -rf ~/.config/claude-code ~/.config/gh ~/.config/gemini
rm -f ~/bin/dev-start

# Then reinstall fresh
npm install -g @nhangen/universal-dev-env
uds init --no-cache

🐛 Known Issues

• Playwright may require additional setup on some Alpine variants
• GitHub CLI authentication needs manual setup in containers
• Some VS Code extensions may not work in web-based environments
• macOS: First-time Homebrew installation may require manual PATH setup
• Windows: Some antivirus software may flag PowerShell script downloads

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the DevContainer specification
• Built with the amazing VS Code Extension API
• Powered by Docker and modern container practices
• Community feedback and contributions

📞 Support

• 🐛 Bug Reports
• 💡 Feature Requests
• 📧 Email Support
• 💬 Discord Community

Made with ❤️ by nhangen
_{Empowering developers with universal, AI-enhanced environments}