A comprehensive set of scripts for setting up a developer-friendly macOS environment with enhanced security, performance, and customization options.
- Interactive Setup: Customize your installation based on your development needs (iOS tools, data science, dev tools)
- Multi-Machine Security: Git hooks enforce security for personal/work machines - blocks secrets, hardcoded paths, requires shellcheck
- Enhanced Security: Secure SSH key management with keychain integration and proper permission handling
- Smart Recovery: Automatic timestamped backups and restoration points for safe rollbacks
- Performance Optimized: PATH deduplication and efficient installation processes
- Comprehensive Logging: Structured logging with levels (INFO, WARN, ERROR, SUCCESS) for better debugging
- System Validation: Pre-installation checks for macOS version, disk space, Xcode tools, and internet connectivity
- macOS: 12.0 (Monterey) or later
- Disk Space: At least 10GB free space
- Internet: Active internet connection required
- Xcode Command Line Tools: Will be installed automatically if missing
# Package managers and build tools
coreutils, git, curl, openssl@3, readline, libyaml, gmp
asdf (version manager), keychain, nmap, tree, ripgrep, tmux, aria2
gh (GitHub CLI), duckdb (in-process SQL OLAP database)
sqlite (lightweight SQL database), beads (distributed git-backed issue tracker for AI agents)
btop (resource monitor with CPU, memory, disk, network, and process stats)
shellcheck (shell script linter), jq (JSON processor)
rtk (Rust Token Killer - CLI proxy for 60-90% token savings in Claude Code)
# Development languages (via asdf)
nodejs 22.9.0 # LTS version, minimum 20.0.0 for modern features
python 3.13.0 # Latest stable, minimum 3.10.0 for type hints
ruby 2.7.7 # Stable version, minimum 2.7.0 for pattern matching
bundler 2.2.32 # Ruby package manager, minimum 2.2.0
gcloud 522.0.0 # Google Cloud SDK for cloud deployments
firebase 14.3.1 # Firebase CLI for Firebase projects
java openjdk-23.0.2 # Java for JVM and Android development
kotlin 2.2.21 # Kotlin for Android and multiplatform development# Xcode management and Swift tools (tap: xcodesorg/made)
xcodes # Xcode version manager
xcode-build-server # Build server for Xcode projects
xcbeautify # Beautify Xcode build logs
swiftlint # Swift linting
swift-format # Swift code formatting
ios-deploy # Deploy iOS apps from command line# Container and Kubernetes tools
k9s # Kubernetes CLI manager
docker # Docker CLI
docker-compose # Multi-container orchestration
colima # Lightweight container runtime for macOS (auto-starts)# Development and productivity
visual-studio-code # Code editor with shell integration
slack # Team communication
postman # API development and testing
raycast # macOS productivity launcher
google-chrome # Web browser
# Utilities
wireshark # Network protocol analyzer
spotify # Music streamingNote: This setup assumes Oh My Zsh is already installed on your system. If not, install it first:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"# Oh My Zsh plugins (installed to ~/.oh-my-zsh/custom)
zsh-autosuggestions # Command suggestions based on history
zsh-syntax-highlighting # Syntax highlighting for commands
powerlevel10k # Modern and customizable prompt theme
# Configured plugins (in .zshrc)
git, asdf, zsh-autosuggestions, zsh-syntax-highlighting, gcloud, docker, tmux
# Shell features configured in .zshrc
- Smart PATH deduplication function
- Secure SSH key management with keychain (ed25519, rsa, ecdsa)
- Enhanced history settings (50k entries, shared across sessions)
- Comprehensive aliases for navigation, git, docker, kubernetes
- Utility functions (mkcd, extract, docker-clean, weather)
- Colima auto-start (opt-in via `SUPERCHARGED_COLIMA_AUTOSTART=1` in `~/.secrets`)
- VS Code shell integration# Dotfiles installed to $HOME
.gitconfig # Git configuration
.gitignore_global # Global gitignore patterns
.tool-versions # ASDF tool versions (all languages)
.zshrc # ZSH configuration with plugins and aliases
.zprofile # ZSH profile (environment variables)
.tmux.conf # tmux configuration
.secrets # Template for secret environment variables
.p10k.zsh # Powerlevel10k theme configuration
# Claude Code configuration (backed up to claude_config/)
settings.json # Claude Code plugin settings
installed_plugins.json # List of installed plugins with versions
known_marketplaces.json # Plugin marketplace configurations# Python packages (pip)
jupyter # Interactive computing environment
pandas # Data manipulation and analysis
numpy # Numerical computing
matplotlib # Data visualization
scikit-learn # Machine learning library- Oh My Zsh: Must be installed before running setup
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
git clone git@github.com:robinsalehjan/supercharged.git
cd supercharged && npm install && npm run setupThe setup process will:
- Copy dotfiles (.gitconfig, .zshrc, .tool-versions, etc.) to your home directory
- Restore Claude Code configuration (settings, plugins) if available
- Validate your system meets requirements (macOS 12.0+, 10GB+ free space, internet)
- Create a timestamped restoration point for safe rollbacks (includes Claude Code config)
- Ask for your preferences:
- iOS development tools? (xcodes, ios-deploy, swift tools) [Y/n]
- Data science tools? (jupyter, pandas, numpy) [y/N]
- Development tools? (docker, kubernetes, colima) [Y/n]
- Claude Code? (AI code assistant) [Y/n]
- Install Homebrew (if not present)
- Install selected tools and applications via Homebrew
- Install ZSH plugins (autosuggestions, syntax-highlighting, powerlevel10k)
- Configure ASDF plugins (python, ruby, nodejs, gcloud, firebase, java, kotlin)
- Install ASDF tool versions from .tool-versions
- Install optional data science tools if selected
- Run validation to ensure all tools are working correctly
npm run updateThis runs a three-step process:
- Backup Claude Code configuration to
claude_config/(with portable paths) - Copy latest dotfiles and Claude Code config to
$HOME(viasetup:profile) - Update installed tools:
- Update Homebrew packages and casks
- Update ASDF plugins and install/update tool versions from
.tool-versions - Run
asdf reshimto update shims - Update ZSH plugins, npm global packages, and pip data science packages
- Clean up Homebrew cache
| Command | Description |
|---|---|
| Setup | |
npm run setup |
Complete fresh installation with interactive configuration |
npm run setup:profile |
Copy dotfiles and Claude Code configuration to $HOME |
| Updates | |
npm run update |
Update all installed packages and tools |
npm run update:dry-run |
Preview outdated Homebrew and npm packages (read-only) |
npm run update:brew |
Copy dotfiles, then update Homebrew (formulae + casks) |
npm run update:asdf |
Copy dotfiles, then update ASDF plugins and versions |
npm run update:zsh |
Update only ZSH plugins |
npm run update:npm |
Update only npm global packages |
npm run update:pip |
Update only pip data science packages |
| Claude Code | |
npm run backup:claude |
Backup Claude Code configuration to claude_config/ (with portable paths) |
npm run restore:claude |
Restore Claude Code config (only if repo is newer) |
npm run restore:claude:force |
Force restore Claude Code config |
| Utilities | |
npm run validate |
Verify all tools are properly installed with correct versions |
npm run restore |
Restore from the most recent backup (~/.supercharged_last_backup) |
npm run lint |
ShellCheck all scripts (ignore zsh warnings) |
npm run help |
Show all available commands |
| Testing | |
npm test |
Run all BATS tests |
npm run test:claude |
Run Claude backup/restore tests only |
npm run test:utils |
Run utility function tests only |
npm run test:mac |
Run mac.sh smoke tests only |
npm run test:update |
Run update.sh smoke tests only |
npm run test:setup |
Run setup-profile.sh smoke tests only |
npm test # Run all tests
npm run test:claude # Run Claude backup/restore tests only
npm run test:utils # Run utility function tests only
npm run test:mac # Run mac.sh smoke tests only
npm run test:update # Run update.sh smoke tests only
npm run test:setup # Run setup-profile.sh smoke tests onlyTests run automatically via pre-commit hook and GitHub Actions. See AGENTS.md for test structure, patterns, and writing guides.
Every installation creates a timestamped backup of your existing configurations in a shared backup directory:
~/.supercharged_backups/ # Hidden shared backup directory
└── 20250929_143022/ # Timestamped backup subdirectory
├── .zshrc
├── .zprofile
├── .gitconfig
├── .p10k.zsh
├── .tool-versions
├── .tmux.conf
├── claude_config/ # Claude Code configuration backup
│ ├── settings.json
│ ├── installed_plugins.json
│ └── known_marketplaces.json
├── brew_packages.txt # List of installed Homebrew packages
├── brew_casks.txt # List of installed Homebrew casks
├── asdf_plugins.txt # List of ASDF plugins
└── asdf_versions.txt # List of installed ASDF versionsAutomatic Cleanup: The system keeps only the last 5 backups and automatically removes older ones to save disk space.
The most recent backup location is saved to ~/.supercharged_last_backup for easy restoration.
If something goes wrong, restore your previous setup:
# Restore from the most recent backup
npm run restore
# Or restore from a specific backup
source scripts/utils.sh && restore_from_backup ~/.supercharged_backups/20250929_143022
# List all available backups
ls -1t ~/.supercharged_backups/All installation activities are logged to:
<supercharged-directory>/.supercharged_install.logEach log entry includes:
- Timestamp (YYYY-MM-DD HH:MM:SS)
- Log level (❌ ERROR,
⚠️ WARN, ℹ️ INFO, ✅ SUCCESS) - Message details
View logs:
cd /path/to/supercharged
tail -f .supercharged_install.log # Follow logs in real-time
grep ERROR .supercharged_install.log # Filter for errorsThis repository runs on both personal and work machines with automated security enforcement: pre-commit hooks (shellcheck, secrets detection, hardcoded paths, large files, tests) and 11 Claude Code hookify rules.
See SECURITY.md for full details.
During setup, you'll be asked about:
- iOS Development Tools [Y/n]: Xcode tools, Swift formatters, iOS deployment tools
- Data Science Tools [y/N]: Jupyter, pandas, numpy, matplotlib, scikit-learn
- Additional Dev Tools [Y/n]: Docker, Kubernetes tools (k9s), Colima
Your preferences are saved to ~/.supercharged_preferences and used during setup. These preferences include:
INSTALL_IOS_TOOLS: Whether to install iOS development toolsINSTALL_DATA_SCIENCE: Whether to install data science packagesINSTALL_DEV_TOOLS: Whether to install Docker and Kubernetes toolsINSTALL_CLAUDE_CODE: Whether to install Claude Code AI assistantSETUP_DATE: When the configuration was last set
Edit these files before running setup:
dot_files/.tool-versions - Add or modify development tool versions:
nodejs 22.9.0
python 3.13.0
ruby 2.7.7
bundler 2.2.32
gcloud 522.0.0
firebase 14.3.1
java openjdk-23.0.2
kotlin 2.2.21
# Add more tools as neededdot_files/.zshrc - Customize shell configuration:
# Navigation aliases: ls, ll, la, cp, mv, mkdir, .., ..., ...., f, c, cdr, path
# Git aliases: gst, gd, gco, gcm, gcd, gcp, gl, gp, glog
# Docker aliases: d, dc
# Kubernetes aliases: k, kx
# Development aliases: py (python3), pip (pip3)
# macOS aliases: showfiles, hidefiles, cleanup
# Utility functions included:
# mkcd - Create directory and cd into it
# extract - Extract various archive formats
# docker-clean - Clean up Docker containers and images
# gb, gcb, gpus, gpul - Git branch utilitiesscripts/mac.sh - Modify package installation lists:
# Edit BREWFILE_CONTENT to add/remove Homebrew packages
# Conditional sections based on INSTALL_IOS_TOOLS, INSTALL_DEV_TOOLS flags
# Core packages always installed:
# coreutils, git, curl, asdf, keychain, tmux, ripgrep, etc.
# iOS tools (conditional):
# xcodes, swift-format, swiftlint, ios-deploy, etc.
# Dev tools (conditional):
# docker, docker-compose, k9s, colima
# Apps always installed:
# VS Code, Slack, Postman, Raycast, Chrome, Wireshark, Spotify"Installation failed" message
# Check the detailed log
cd /path/to/supercharged
tail -f .supercharged_install.log
# Restore from backup if needed
npm run restore"System validation failed"
# Ensure you meet requirements:
sw_vers -productVersion # Check macOS version (needs 12.0+)
df -h / # Check disk space (needs 10GB+)
xcode-select -p # Check command line tools
ping -c 1 google.com # Check internet connectivity"Oh My Zsh plugins not working"
# Ensure Oh My Zsh is installed first
ls -la ~/.oh-my-zsh
# If not installed:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
# Then rerun setup
npm run setup"SSH key issues"
# Check SSH key status
ls -la ~/.ssh/
ssh-add -l
# The setup configures keychain for automatic SSH key loading
# Supported key types: ed25519 (preferred), rsa, ecdsa
# Keys are automatically loaded via keychain in .zshrc"ASDF version not found"
# List available versions
asdf list all nodejs
# Install specific version
asdf install nodejs 22.9.0
# Set version globally (note: use 'asdf set' not 'asdf global')
asdf set --home nodejs 22.9.0
# Reshim to update PATH
asdf reshim"Java showing wrong version"
# Check asdf current versions
asdf current
# Reload shell to pick up new PATH
exec zsh
# Or source zshrc
source ~/.zshrc# Restore from backup first
npm run restore