Dotfiles

Automate macOS workstation setup with Ansible. The playbook installs Homebrew packages, copies shell and editor configuration, configures global Git identity, writes Worktrunk shell integration, and installs Pi agent settings.

Bootstrap requirements

Install and sign in to the 1Password CLI before running the playbook. ansible.cfg uses ./vault-password.sh, which reads the Ansible vault password from 1Password:

op signin
op read "op://Private/dotfiles Ansible vault/password"

Install Ansible before the first run if the machine does not have it yet:

brew install ansible

Hosts

Both inventory entries target localhost:

• home configures the home laptop.
• work configures the work laptop.

Always pass --limit so Ansible loads one host's variables and does not run against both entries.

ansible-playbook site.yml --limit home
ansible-playbook site.yml --limit work

Repository layout

• site.yml installs packages and runs configuration roles.
• inventory.yml defines the home and work localhost targets.
• ansible.cfg sets inventory, roles_path, and vault_password_file.
• group_vars/all.yml defines shared Homebrew packages, casks, config file mappings, Git variables, and Pi agent packages.
• host_vars/<host>/vars.yml defines host-specific non-secret values such as ansible_user, ansible_group, Python interpreter, and config_files_host for config files rendered only on that host.
• host_vars/<host>/vault.yml stores vaulted host secrets such as Git name and email.
• roles/config_files/ templates files from templates/ into the home directory.
• roles/git/ configures global Git identity and excludes.
• roles/osx_settings/ sets macOS system preferences via community.general.osx_defaults, without become.
• roles/pi_agent/ merges Pi settings.json and mcp.json without replacing unrelated existing keys.
• templates/ contains managed dotfiles, editor settings, agent skills, and Codex rules.

What the playbook manages

The main playbook performs these steps:

1. Install Homebrew taps from homebrew_taps.
2. Update Homebrew (refresh tap/formula metadata only — no machine-wide upgrade).
3. Install and keep current the formulae in homebrew_packages (only those, not anything else installed on the machine).
4. Install and keep current the casks in homebrew_casks (only those; self-updating casks are left to their own updater, per Homebrew's own outdated-check logic). On first install, if a cask's target app path is already occupied (e.g. a manually installed app), the task fails loudly instead of silently adopting or overwriting it.
5. Copy templated config files listed in config_files.
6. Configure global Git user name, email, and excludes file.
7. Configure macOS defaults, restarting affected apps only when a preference changes.
8. Create ~/.config/mise/conf.d.
9. Generate Worktrunk shell integration at ~/.zshrc.worktrunk.
10. Configure Pi agent settings and MCP servers.
11. Run mise upgrade and pi update --extensions after the main tasks.

Vault files

Host-specific variables are split so Ansible can auto-load plain values and encrypted secrets for the selected host:

host_vars/
  home/
    vars.yml
    vault.yml
  work/
    vars.yml
    vault.yml

Edit vaulted files with Ansible Vault so vault-password.sh can fetch the password from 1Password:

ansible-vault edit host_vars/home/vault.yml
ansible-vault edit host_vars/work/vault.yml

Encrypt a new or decrypted vault file with:

ansible-vault encrypt host_vars/home/vault.yml
ansible-vault encrypt host_vars/work/vault.yml

Validation

Check syntax before applying changes:

ansible-playbook site.yml --limit home --syntax-check
ansible-playbook site.yml --limit work --syntax-check

Preview the task list for one host:

ansible-playbook site.yml --limit home --list-tasks

Run check mode when you need a dry run:

ansible-playbook site.yml --limit home --check --diff
ansible-playbook site.yml --limit work --check --diff