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

code

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

ruby

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

Step 3: Install Layer

bash

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

Package Types

Brew Formulas

ruby

brew "package-name"

Casks (macOS Applications)

ruby

cask "application-name"

Taps (Third-party Repositories)

ruby

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

Installation Workflow

Initial Installation

bash

# 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

bash

# 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

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

Anti-Patterns

❌ Don't Do This

ruby

# 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

ruby

# 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