Customization

This guide covers common ways to extend or modify the mac-setup setup.

Adding a Homebrew Formula

1. Open roles/homebrew/vars/main.yml
2. Add the formula name to the homebrew_formulae list
3. Run make setup

Alternatively, install the formula normally with brew install <name>, then run make cleanup — the cleanup step will detect it as unmanaged and prompt you to either add it to the list or remove it.

Adding a Homebrew Cask

Same pattern as formulae, but use the homebrew_casks list in roles/homebrew/vars/main.yml.

homebrew_casks:
  - firefox
  - rectangle
  - your-new-cask    # add here

The playbook sets accept_external_apps: true, which means apps that were installed outside of Homebrew (e.g., downloaded directly from a website) are detected and skipped rather than causing an error.

Adding a VS Code Extension

1. Open roles/apps/vars/main.yml
2. Add the extension identifier to the vscode_extensions list
3. Run make setup

Extension identifiers use the publisher.extension format (e.g., ms-python.python). You can find the identifier on the VS Code Marketplace or by running code --list-extensions.

Adding an App Config

To bring a new application’s config under management:

1. Place config files in configs/<app>/ — mirror the structure the app expects
2. Add a symlink task to the relevant role in roles/<role>/tasks/main.yml:

   - name: Symlink <app> config
     ansible.builtin.file:
       src: "{{ repo_dir }}/configs/<app>/config-file"
       dest: "~/.config/<app>/config-file"
       state: link
       force: true

3. Add validation to scripts/validate.sh to verify the symlink is correct:

   check_symlink "$HOME/.config/<app>/config-file" "$MAC_SETUP_DIR/configs/<app>/config-file"

Adding a Raycast Script Command

Raycast script commands live in configs/raycast/script-commands/. To add one:

1. Create a new .sh, .py, or .applescript file in that directory
2. Include the required Raycast metadata headers at the top of the file:

   #!/bin/bash
   
   # Required parameters:
   # @raycast.schemaVersion 1
   # @raycast.title My Script
   # @raycast.mode compact
   
   # Optional parameters:
   # @raycast.icon
   # @raycast.packageName My Package
   
   echo "Hello from Raycast"

3. Make the file executable: chmod +x configs/raycast/script-commands/my-script.sh

The Ansible playbook uses a find task to auto-discover all script files in that directory, so no additional configuration is needed.

Removing Packages

To remove a formula or cask that was previously managed:

1. Remove it from homebrew_formulae or homebrew_casks
2. Add it to the corresponding removal list:
   • homebrew_formulae_absent for formulae
   • homebrew_casks_absent for casks
3. Run make setup

The playbook will uninstall the package on the next run.

Adding Mise Runtimes

To add or change globally managed runtimes (Node.js, Python, Go, etc.):

1. Edit configs/mise/config.toml
2. Add or update the tool version:

   [tools]
   node = "lts"
   python = "3.12"
   go = "latest"       # add new runtime here

3. Run make setup to install the runtime

Adding npm Global Packages

To add globally installed npm packages (managed through Mise’s Node.js):

1. Open roles/mise/vars/main.yml
2. Add the package name to the npm_global_packages list:

   npm_global_packages:
     - prettier
     - eslint
     - your-package    # add here

3. Run make setup