ansible-local/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an Ansible playbook for local machine configuration and application installation. It automates the setup of shell environments, development tools, and applications across multiple operating systems (macOS, Linux distributions).

Architecture

The playbook is structured around two main roles:

• shell role: Configures shell environment (ZSH, Starship prompt, Meslo font, dotfiles via GNU Stow)
• apps role: Installs package managers and applications across different OS platforms

Key Commands

Running the playbook

# Install Ansible collections first
ansible-galaxy install -r requirements.yml

# Run the full playbook
ansible-playbook main.yml

# Run specific roles with tags
ansible-playbook main.yml --tags=zsh
ansible-playbook main.yml --tags=starship
ansible-playbook main.yml --tags=meslo_font
ansible-playbook main.yml --tags=dotfiles
ansible-playbook main.yml --tags=package_managers
ansible-playbook main.yml --tags=apps

# Check what would be changed (dry run)
ansible-playbook main.yml --check

# Run with increased verbosity
ansible-playbook main.yml -v

Project Structure

• main.yml: Main playbook entry point, runs on localhost with privilege escalation
• requirements.yml: Ansible collection dependencies (community.general)
• roles/shell/: Shell environment configuration tasks
• roles/apps/: Application installation and package manager setup tasks

Cross-Platform Support

The playbook supports multiple operating systems:

• macOS: Uses Homebrew for package management
• Debian/Ubuntu: Uses APT package manager
• RedHat/CentOS/Fedora: Uses YUM/DNF package managers
• Arch Linux: Uses Pacman package manager
• Linux (general): Uses AppMan for universal Linux app management

Development Notes

• Tasks are organized by function with conditional execution based on ansible_os_family
• All tasks include appropriate become directives for privilege requirements
• Package managers are installed before applications in the apps role
• Shell configuration includes font installation, prompt customization, and dotfile management