From Zero to Hero — An opinionated macOS development environment setup guide for engineers.
Ship Fast. Break Things. Fix Faster.
- Minimal Friction — One-click setup, zero resistance to start coding
- Battle-Tested — Production-proven toolchain used by top engineers
- Opinionated — Curated choices so you don't waste time deciding
- Reproducible — Consistent environment across all your machines
Use Claude Code for a personalized, conversational setup experience:
# Clone this repo
git clone https://github.com/larrykoo711/new-macos-starter.git
cd new-macos-starter
# Start the interactive setup wizard in Claude Code:
/new-macos-setupThe AI wizard will:
- Detect what's already installed on your system
- Ask your preferences (role, languages, apps)
- Generate a customized installation plan
- Execute step-by-step with progress tracking
# Quick setup with sensible defaults
/new-macos-setup --quick
# Use a preset (fullstack, frontend, backend, data, devops)
/new-macos-setup --preset fullstack
# Preview plan without installing
/new-macos-setup --dry-run# Clone this repo
git clone https://github.com/larrykoo711/new-macos-starter.git
cd new-macos-starter
# Run the bootstrap script (installs prerequisites only)
./scripts/bootstrap.shThe bootstrap script will install Xcode CLI Tools, Rosetta 2 (if Apple Silicon), and Homebrew. Then it guides you to use the AI-powered /new-macos-setup command for complete configuration.
| Category | Tool | Why |
|---|---|---|
| Package Manager | Homebrew | The standard package manager for macOS |
| Shell | Zsh + Oh-My-Zsh + Starship | Modern shell experience with beautiful prompts |
| Terminal | Ghostty + tmux | Open-source GPU-accelerated terminal with multiplexer (Warp as alt) |
| Launcher | Raycast | Spotlight replacement + window management |
| Version Control | Git + gh CLI | Native GitHub integration |
| Category | Tool | Why |
|---|---|---|
| Node.js | fnm + pnpm | Fast version management + efficient package manager |
| Python | uv | Rust-built, manages both versions and dependencies |
| Go | goenv | Multi-version management |
| Container | OrbStack | Lightweight Docker/K8s (replaces Docker Desktop) |
| Kubernetes | kubectl + helm + k9s + kubeswitch | Complete cloud-native toolkit |
| Tool | Description |
|---|---|
| VS Code | Primary editor (free, mature, great extension ecosystem) |
| Claude Code extension for VS Code | Native AI pair-programming inside the editor |
| Tool | Description |
|---|---|
| Claude Code | Anthropic's official agentic CLI (recommended) |
| OpenCode | Open-source terminal AI coding tool |
| Cherry Studio | Multi-model AI desktop client |
| Category | Apps |
|---|---|
| Must Have | Raycast, 1Password, Chrome, KeepingYouAwake, Keka |
| Development | VS Code, Ghostty, Warp, OrbStack, Proxyman, Sourcetree |
| Communication (CN) | Lark, WeChat, Tencent Meeting |
| AI Tools | Claude Code, Cherry Studio |
| System | iStat Menus, MonitorControl, Gas Mask |
| Chapter | Description |
|---|---|
| 00. Troubleshooting | Common issues and solutions |
| 01. System Setup | Initial system configuration |
| 02. Homebrew | Package manager installation |
| 03. Shell | Zsh + Oh-My-Zsh configuration |
| 04. Fonts | Programming fonts installation |
| 05. Dev Environment | Git, Node.js, Python, Go, Container |
| 06. Editor | VS Code + Claude Code configuration |
| 07. Vibe Coding | AI-assisted programming tools |
| 08. Apps | Recommended applications |
| 09. macOS | System optimization |
| 10. Network (China) | China network mirrors & proxy |
macOS-Starter/
├── .claude/
│ ├── commands/
│ │ └── new-macos-setup.md # /new-macos-setup command entry point
│ └── skills/
│ └── macos-setup/ # AI setup wizard skill
│ ├── SKILL.md # Skill definition + Q&A flow
│ ├── presets.md # Role-based presets (5 profiles)
│ └── packages.md # Complete package registry
├── scripts/
│ ├── bootstrap.sh # Prerequisites installer (Homebrew)
│ ├── verify.sh # Installation verification script
│ └── Brewfile # Homebrew package definitions
├── configs/
│ ├── shell/ # .zshrc (optimized), .zprofile
│ ├── git/ # .gitconfig, .gitignore_global
│ ├── editors/ # VS Code settings, Biome config
│ └── terminal/ # Starship prompt config
└── docs/ # Detailed reference guides (01-09)
After running bootstrap.sh, complete these manual configurations:
# 1. Setup Node.js
fnm install --lts
fnm default lts-latest
# 2. Setup Python
uv python install 3.13
# 3. Configure Git (edit with your info)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"See the documentation for detailed guides.
After setup, verify all tools are properly installed:
./scripts/verify.sh| Component | Version |
|---|---|
| macOS | Sequoia 15.x / Sonoma 14.x |
| Architecture | Apple Silicon (M1/M2/M3/M4) / Intel |
| Homebrew | 4.x |
| Node.js | 22.x LTS |
| Python | 3.12+ |
| Go | 1.23+ |
Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting a PR.
- Found a bug? Open an issue
- Have a feature idea? Start a discussion
- Want to contribute? Submit a PR
MIT License — Use it, modify it, ship it.
Inspired by the engineering cultures at YC startups, Silicon Valley companies, and the open-source community.
Built with focus by engineers, for engineers.