Homebrew Layers

Core Philosophy

The toolchain-2026 uses a layered approach similar to Spacemacs bundles:

• Base Layer (Brewfile.base) - Universal foundation (git, bash, coreutils)
• Domain Layers - Specialized tool sets (ai, web, data, cloud, mobile, security)
• macOS Layer (Brewfile.macos) - macOS-specific applications
• Large Layer (Brewfile.large) - Large packages (filtered by installed layers)

Layer Structure

Brewfile.base      # Universal foundation
Brewfile.ai        # AI development tools
Brewfile.web       # Web development
Brewfile.data      # Data science tools
Brewfile.cloud     # Cloud/DevOps tools
Brewfile.mobile    # Mobile development
Brewfile.security  # Security and scanning tools
Brewfile.macos     # macOS-specific apps
Brewfile.large     # Large packages (filtered)

Adding Packages

Step 1: Determine the Correct Layer

Base Layer (Brewfile.base):

• Universal tools used by everyone
• Core development tools (git, bash, coreutils)
• Essential utilities (fzf, ripgrep, bat)

Domain Layers:

• Brewfile.ai - AI/ML tools (ollama, llama.cpp, etc.)
• Brewfile.web - Web dev (node, npm, browsers)
• Brewfile.data - Data science (python, jupyter, etc.)
• Brewfile.cloud - Cloud tools (terraform, kubectl, etc.)
• Brewfile.mobile - Mobile dev (flutter, react-native, etc.)
• Brewfile.security - Security tools (gitleaks, pre-commit, etc.)

macOS Layer (Brewfile.macos):

• GUI applications (Cursor, Raycast, Rectangle)
• macOS-specific tools

Large Layer (Brewfile.large):

• Large packages (Xcode, Docker Desktop, etc.)
• Filtered based on installed layers

Step 2: Add to Brewfile

# Brewfile.ai example
brew "ollama"
brew "llama.cpp"
cask "cursor"  # Actually in Brewfile.macos, but example

Step 3: Install Layer

./install.sh --ai  # Install AI layer
./install.sh --add web  # Add web layer to existing install

Package Types

Brew Formulas

brew "package-name"

Casks (macOS Applications)

cask "application-name"

Taps (Third-party Repositories)

tap "owner/tap-name"
brew "package-from-tap"

Installation Workflow

Initial Installation

# Bootstrap (installs Homebrew, bash 4+, etc.)
./bootstrap.sh

# Install base layer
./install.sh --base

# Install specific layers
./install.sh --base --ai --web

Adding Layers Later

# Add a layer to existing installation
./install.sh --add mobile

# List available layers
./install.sh --list

Layer Dependencies

Some layers depend on others:

• All layers depend on base
• large is filtered based on installed layers

Best Practices

1. Keep base layer minimal - Only universal tools
2. One package per line - Easy to review and maintain
3. Group related packages - Use comments to organize
4. Document special cases - Note any quirks or requirements
5. Test on clean system - Verify installation works from scratch

Anti-Patterns

❌ Don't Do This

# Adding everything to base
brew "specialized-tool"  # Should be in domain layer

# Duplicating packages across layers
brew "package"  # In multiple layers

# Adding large packages to base
brew "xcode"  # Should be in large layer

✅ Do This Instead

# Base layer - only universal tools
brew "git"
brew "bash"

# Domain layer - specialized tools
brew "ollama"  # In Brewfile.ai

# Large layer - large packages
brew "xcode"  # In Brewfile.large

Integration with Other Skills

• bash-scripting: Scripts that manage Brewfiles
• security-scanning: Verify no secrets in package configs

References

• install.sh - Layer-based installer
• Brewfile.* - Layer definitions
• learning/LEARNING_LOG.md - Package management lessons