Skip to content

AGENT.md

Latest commit

 

History

History
539 lines (407 loc) · 10.8 KB

AGENT.md

File metadata and controls

539 lines (407 loc) · 10.8 KB
Raw

AI Agent Reference Guide

Complete reference for AI assistants (Cursor, Claude, etc) working with this repo

🎯 Purpose

This repo is designed for AI collaboration. YAML-based config, modular structure, clear commands. AI can read, understand, modify, and execute.

🏗️ System Architecture

Core Components

categories.yml - YAML config defining 14 categories

  • Priority ordering (1-99)
  • Dependencies
  • Brewfile paths
  • Setup scripts
  • Required vs optional

install.sh - Interactive installer

  • YAML parser (no external deps)
  • Menu system
  • Priority-based execution
  • Dependency handling

categories/*.Brewfile - 12 split Brewfiles

  • One per category
  • Clean, commented
  • Individual or batch install

scripts/category - CLI management

  • List categories
  • Install specific category
  • Simple commands

scripts/install-parallel - Fast parallel installer

  • Multi-category simultaneous install
  • 50% faster than sequential
  • Automatic batching

File Structure

config/
├── categories.yml          # ⭐ Edit this to add/modify categories
├── install.sh             # Main installer
├── categories/            # ⭐ Split Brewfiles
│   ├── cli_essentials.Brewfile
│   ├── shell_tools.Brewfile
│   ├── languages.Brewfile
│   ├── web_dev.Brewfile
│   ├── databases.Brewfile
│   ├── cloud_tools.Brewfile
│   ├── editors.Brewfile
│   ├── browsers.Brewfile
│   ├── terminals.Brewfile
│   ├── productivity.Brewfile
│   ├── entertainment.Brewfile
│   └── fonts.Brewfile
├── scripts/
│   ├── category          # Category CLI
│   └── install-parallel  # Fast parallel installer
├── setup/
│   ├── shell.sh         # Oh My Zsh setup
│   ├── languages.sh     # Language runtime config
│   └── symlinks.sh      # Dotfile linking
├── dotfiles/
│   ├── .aliases         # Shell aliases
│   └── .functions       # Shell functions
└── macos.sh            # System preferences

📦 Categories Reference

Full Category List

ID Name Priority Contains
password_manager Password Manager 1 Bitwarden
cli_essentials CLI Essentials 2 git, gh, fd, tree, wget, mkcert, direnv
shell_tools Shell Tools 3 zsh plugins, starship, tmux, hstr
languages Language Runtimes 4 Node, Python, Ruby, Go
web_dev Web Development 5 Docker, ngrok, biome
databases Database Tools 6 PostgreSQL, CockroachDB, DBeaver
cloud_tools Cloud & DevOps 7 GCloud, Ansible, Fly.io
editors Code Editors 8 Cursor, VSCode, Sublime
browsers Web Browsers 9 Brave, Firefox
terminals Terminal Apps 10 iTerm2, Warp
productivity Productivity 11 Slack, Discord, Zoom, Rectangle
entertainment Entertainment 12 Spotify
fonts Fonts 13 Hack Nerd Font
dotfiles Dotfiles 98 Config symlinks
macos_prefs macOS Prefs 99 System settings

Dependencies

  • web_dev depends on cli_essentials
  • All others independent

🤖 Commands AI Can Run

Information

# List all categories
scripts/category list

# Show category details
cat categories.yml | grep -A 10 "id: cli_essentials"

# View Brewfile contents
cat categories/web_dev.Brewfile

# Check what's installed
brew list --formula
brew list --cask

# Show file structure
tree -L 2 -a

Installation

# Install single category
scripts/category install cli_essentials

# Install multiple (sequential)
scripts/category install databases
scripts/category install editors

# Install all (interactive)
./install.sh

# Install all (parallel, fast)
scripts/install-parallel

# Install specific Brewfile
brew bundle --file=categories/languages.Brewfile

Modification

# Add app to category
echo 'brew "ripgrep"' >> categories/cli_essentials.Brewfile

# Edit category config
# Open categories.yml and add/modify

# Test changes
scripts/category install cli_essentials

Parallel Execution

# Fast install (automatic)
scripts/install-parallel

# Manual parallel (3 categories)
brew bundle --file=categories/cli_essentials.Brewfile &
brew bundle --file=categories/editors.Brewfile &
brew bundle --file=categories/browsers.Brewfile &
wait

✏️ How to Modify

Add App to Existing Category

  1. Identify category:
scripts/category list
  1. Edit Brewfile:
echo 'brew "fzf"' >> categories/cli_essentials.Brewfile
  1. Install:
scripts/category install cli_essentials

Create New Category

  1. Edit categories.yml:
- id: ml_tools
  name: Machine Learning Tools
  priority: 14
  required: false
  description: ML frameworks and tools
  brewfile: categories/ml_tools.Brewfile
  setup_script: null
  1. Create Brewfile:
cat > categories/ml_tools.Brewfile << 'EOF'
# Machine Learning Tools

brew "python@3.11"
cask "anaconda"
# Add more...
EOF
  1. Test:
scripts/category install ml_tools

Modify Installation Order

Edit priority in categories.yml:

  • Lower number = installs first
  • Use gaps (1, 2, 5, 10) for future insertions

Add Setup Script

  1. Create script:
cat > setup/ml_tools.sh << 'EOF'
#!/usr/bin/env bash
echo "Configuring ML tools..."
# Setup commands
EOF

chmod +x setup/ml_tools.sh
  1. Reference in categories.yml:
setup_script: setup/ml_tools.sh

🎨 Common AI Tasks

"List all categories"

scripts/category list

"What's in the web_dev category?"

cat categories/web_dev.Brewfile

"Install database tools"

scripts/category install databases

"Add ripgrep to CLI tools"

echo 'brew "ripgrep"' >> categories/cli_essentials.Brewfile
scripts/category install cli_essentials

"Create ML category"

See "Create New Category" section above

"Install everything fast"

scripts/install-parallel

"Show what would be installed"

cat categories/*.Brewfile | grep -E "^(brew|cask)"

"Check if app installed"

brew list | grep docker
brew list --cask | grep cursor

⚡ Parallel Installation

Why Use Parallel?

  • 50% faster than sequential
  • Multiple categories install simultaneously
  • Better resource utilization

How It Works

Batching strategy:

  1. Batch 1: All independent categories (parallel)
  2. Batch 2: Dependent categories (after dependencies met)
  3. Batch 3: Interactive categories (sequential)

Example:

# These run simultaneously
brew bundle --file=categories/cli_essentials.Brewfile &
brew bundle --file=categories/editors.Brewfile &
brew bundle --file=categories/browsers.Brewfile &
wait  # Wait for all to complete

Usage

Automatic:

scripts/install-parallel
# Handles batching automatically
# Logs to /tmp/brew_install_*.log

Manual:

# Install 3 categories in parallel
brew bundle --file=categories/cat1.Brewfile &
brew bundle --file=categories/cat2.Brewfile &
brew bundle --file=categories/cat3.Brewfile &
wait

Check logs:

cat /tmp/brew_install_cli_essentials.log

🔍 Troubleshooting

Category Won't Install

Check Brewfile exists:

ls -la categories/

Check Brewfile syntax:

cat categories/CATEGORY.Brewfile

Manual install:

brew bundle --file=categories/CATEGORY.Brewfile

Parallel Install Failed

Check logs:

cat /tmp/brew_install_*.log

Retry specific category:

scripts/category install CATEGORY_ID

Fallback to sequential:

./install.sh

App Not Installing

Check Homebrew:

brew doctor

Search for app:

brew search APP_NAME

Check if cask or formula:

brew info APP_NAME

📝 YAML Schema

Category Definition

- id: category_id              # Unique identifier
  name: Display Name           # Human-readable name
  priority: 1                  # Install order (1-99)
  required: false              # Auto-install if true
  description: Brief desc      # What this category does
  brewfile: categories/file.Brewfile  # Path to Brewfile (or null)
  setup_script: setup/script.sh       # Post-install script (or null)
  post_install: "Message text"        # Optional message after install
  depends_on: [other_category]       # Optional dependencies

Brewfile Syntax

# Formulae (CLI tools)
brew "git"
brew "node"

# Casks (GUI apps)
cask "docker"
cask "cursor"

# Taps
tap "homebrew/cask-fonts"

# Comments for organization
# More packages...

🎯 Best Practices

For AI Agents

  1. Always check before modifying:
cat categories.yml  # Review structure
cat categories/TARGET.Brewfile  # Check current contents
  1. Use proper syntax:
  • Brewfile: brew "package" or cask "app"
  • YAML: Maintain indentation (2 spaces)
  1. Test changes:
scripts/category install CATEGORY_ID
  1. Explain what you're doing:
  • Tell user what category you're modifying
  • Show what you're adding/changing
  • Explain expected outcome
  1. Handle errors gracefully:
  • Check logs if install fails
  • Suggest alternatives
  • Provide debugging commands

Modification Workflow

  1. Understand request
  2. Check current state
  3. Propose changes
  4. Make modifications
  5. Test if possible
  6. Confirm completion

🔐 Security Notes

Don't commit:

  • SSH private keys
  • API tokens
  • Passwords
  • .env files with secrets

Handled by .gitignore:

  • *.pem, *.key
  • .env, .env.local
  • secrets/, private/
  • .bw-session

📊 Performance

Sequential install: ~20-30 minutes Parallel install: ~10-15 minutes Speedup: 40-50%

Resource usage (parallel):

  • CPU: Higher utilization
  • RAM: 8GB+ recommended
  • Network: Multiple simultaneous downloads

🎓 Technical Notes

YAML Parser:

  • Simple bash regex-based
  • No external dependencies
  • Handles our schema perfectly
  • ~50 lines of code

Homebrew Behavior:

  • Idempotent (safe to re-run)
  • Internal parallelization within bundle
  • Some operations still serialize due to locks

Category System:

  • Priority-based ordering
  • Dependency tracking
  • Modular execution
  • Post-install hooks

💡 Quick Reference

List categories: scripts/category list Install one: scripts/category install ID Install all: ./install.sh or scripts/install-parallel View Brewfile: cat categories/NAME.Brewfile Edit config: vim categories.yml Add app: echo 'brew "app"' >> categories/FILE.Brewfile Check logs: cat /tmp/brew_install_*.log

This repo is designed for AI collaboration. Parse YAML, run commands, modify configs, test changes. All tools provided.