Category-based dotfiles system for streamlined Mac development environment setup
Modular, YAML-configured installation system with 14 categories. Install all, some, or one at a time. Works with or without AI assistance.
# 1. Install Xcode CLI tools
xcode-select --install
# 2. Clone repo
git clone https://github.com/YOUR_USERNAME/mac-setup.git ~/mac-setup
cd ~/mac-setup
# 3. Run installer
./install.shInteractive menu appears - select categories or "A" for all.
cd ~/mac-setup
# List categories
scripts/category list
# Install specific category
scripts/category install cli_essentials
# Or interactive menu
./install.sh
# Or fast parallel install
scripts/install-parallel # 50% faster!14 modular categories, each independently installable:
| Priority | Category | Description |
|---|---|---|
| 1 | password_manager | Bitwarden (required, installs first) |
| 2 | cli_essentials | git, gh, fd, tree, wget, mkcert, direnv |
| 3 | shell_tools | Oh My Zsh + plugins (auto-configured), starship, tmux, hstr |
| 4 | languages | Node, Python, Ruby, Go + version managers |
| 5 | web_dev | Docker, ngrok, biome, sentry-cli |
| 6 | databases | PostgreSQL, CockroachDB, DBeaver, Turso |
| 7 | cloud_tools | GCloud, Ansible, Fly.io, Cloudflare |
| 8 | editors | Cursor, VSCode, Sublime Text |
| 9 | browsers | Brave, Firefox |
| 10 | terminals | iTerm2, Warp |
| 11 | productivity | Slack, Discord, Zoom, Rectangle |
| 12 | entertainment | Spotify |
| 13 | fonts | Nerd Fonts for terminal |
| 98 | dotfiles | Config file symlinks |
| 99 | macos_prefs | System preferences automation |
- 🧩 Modular - 14 independent installation categories
- ⚡ Fast - Parallel install mode (50% faster)
- 🤖 AI-Friendly - YAML config, designed for LLM assistance
- 🔄 Idempotent - Safe to run multiple times
- 🎨 Interactive - Menu-driven or CLI
- 📦 No Dependencies - Just bash + Homebrew
- 🔐 Bitwarden First - Password manager installs before everything
./install.shSelect from menu, install one or all categories.
scripts/category install cli_essentials
scripts/category install databases./install.sh
# Select 'G' for Git Configuration SetupFollows the macOS Setup Guide for complete Git configuration including:
- User name and email setup
- Credential helper configuration
- SSH key generation and GitHub setup
- Additional Git preferences
scripts/install-parallel # 50% fasterInstalls multiple categories simultaneously.
brew bundle --file=categories/web_dev.Brewfilemac-setup/
├── categories.yml # Category definitions (YAML)
├── install.sh # Interactive installer
├── categories/ # Split Brewfiles (12 files)
│ ├── cli_essentials.Brewfile
│ ├── languages.Brewfile
│ ├── web_dev.Brewfile
│ └── ...
├── scripts/
│ ├── category # Category management CLI
│ └── install-parallel # Fast parallel installer
├── setup/
│ ├── shell.sh
│ ├── languages.sh
│ └── symlinks.sh
├── mac-setup/
│ ├── .aliases
│ └── .functions
├── macos.sh # System preferences
├── README.md # This file
├── AGENT.md # AI assistant reference
└── DEVELOPMENT.md # Dev notes & improvementsList all categories:
scripts/category listInstall specific category:
scripts/category install databasesAdd app to existing category:
echo 'brew "ripgrep"' >> categories/cli_essentials.Brewfile
scripts/category install cli_essentialsAdd new category:
- Edit
categories.yml - Create
categories/new_category.Brewfile - Test:
scripts/category install new_category
This repo is designed for AI collaboration. Using Cursor or similar:
"List all installation categories"
"What's in the web_dev category?"
"Install only database tools"
"Add ripgrep to CLI essentials"
"Create new category for ML tools"
See AGENT.md for AI assistant reference guide.
- README.md - This file (overview, quick start)
- AGENT.md - AI assistant reference (for Cursor, Claude, etc)
- DEVELOPMENT.md - Dev notes, improvements, technical details
Readable - YAML config, clear structure Maintainable - Modular files, easy to edit Scalable - Add categories without core changes LLM-friendly - AI can parse and modify Zero-dependency - Works on fresh Mac (bash + brew)
- macOS (tested on Sequoia 24.6.0)
- Xcode Command Line Tools
- Homebrew (auto-installed if missing)
Phase: ✅ Production Ready
Features:
- ✅ 14 modular categories
- ✅ YAML configuration
- ✅ Interactive + parallel modes
- ✅ Category management CLI
- ✅ Complete documentation
- ✅ AI-friendly design
Stats:
- Categories: 14
- Brewfiles: 12
- Scripts: 3
- Total packages: ~60+
MIT - Use freely
Inspired by:
Built with ❤️🤝🤖 for efficient Mac setups