provision/CLAUDE.MD

CLAUDE.MD - AI Assistant Guide

Project Overview

System provisioning tool for macOS and Linux desktop computers. Simple, idempotent shell scripts (~600 LOC) that automate installation of dev tools, GUI apps, and dotfiles.

Philosophy: "JFUI" (Just Use It) - simple, fast, idempotent, self-contained.

Main Script: provision - orchestrates all installation steps

Structure

provision/
├── provision              # Main entry point
├── bootstrap              # Fresh system bootstrap
├── lib/
│   ├── common.sh         # Platform detection, logging
│   └── package.sh        # Package manager abstraction
├── scripts/
│   ├── packages.sh          # CLI tools & X11 (Linux)
│   ├── apps.sh              # GUI apps
│   ├── golang.sh            # Go from tar.gz
│   ├── plan9port.sh         # Plan9 from source
│   ├── user-setup.sh        # User & SSH setup
│   ├── macos-defaults.sh    # macOS system defaults
│   ├── elementary-defaults.sh # elementary OS system defaults
│   └── update-xdm.sh        # XDM config updater (Linux)
└── config/                # Dotfiles & configs
    ├── bashrc, tmux.conf, starship.toml, gitconfig
    ├── xinitrc, xsession, Xresources  # X11 (Linux)
    └── twm/, xdm/        # TWM & XDM configs (Linux)

Platforms

• macOS: Homebrew
• Debian/Ubuntu: apt (includes Pop!_OS, Linux Mint, other Debian derivatives)
• elementary OS: apt (X11/TWM setup skipped - uses native Pantheon desktop)
• Arch Linux: pacman + AUR

What Gets Installed

CLI Tools: git, curl, wget, tmux, jq, starship, gh, 1Password CLI, Tailscale, Meslo Nerd Font, TPM (tmux plugins)

Linux X11 (skipped on elementary OS): twm, slock, xsetroot, feh, xclock, xload, xdm

GUI Apps (skip with --skip-apps): VSCodium, 1Password, Obsidian, Chrome, Todoist, Claude Desktop

Development (skip with flags):

• Go → /usr/local/go (--skip-go)
• Plan9port → /usr/local/plan9 (--skip-p9)

Work packages (--work): Slack, Zoom

Config: Bash, tmux, starship, git. Linux: X11/TWM with Dracula theme & 1.5x DPI

Usage

./provision              # Full provision
./provision --skip-apps  # No GUI apps
./provision --skip-go    # No Go
./provision --skip-p9    # No Plan9
./provision --work       # Include work tools

Bootstrap fresh system:

curl -fsSL https://git.sdf.org/jchenry/provision/raw/branch/main/bootstrap | bash

Key Implementation

Package abstraction (lib/package.sh):

install_package <name> [debian] [arch] [brew]
install_cask <name>  # macOS only
install_aur <name>   # Arch only

Platform detection (lib/common.sh):

• $OS_TYPE: "macos", "debian", "arch"
• Helpers: is_macos, is_linux, is_debian, is_arch, is_elementary

Logging: log_info, log_success, log_warn, log_error

Idempotency: All scripts check existing installations before proceeding

Linux X11/TWM Setup

Note: X11/TWM setup is skipped on elementary OS (uses native Pantheon desktop).

Complete lightweight X11 environment for Debian/Ubuntu/Arch:

• XDM: Display manager with Dracula theme
• TWM: Window manager with custom config
• DPI: 1.5x default (144). Edit config/Xresources, config/xinitrc, config/xsession
  • 96=1x, 144=1.5x, 192=2x
• Theme: Dracula throughout

Update XDM after changes:

./scripts/update-xdm.sh
sudo systemctl restart xdm

elementary OS Setup

Custom configuration for elementary OS (scripts/elementary-defaults.sh):

Prerequisites (auto-installed):

• git
• gtk2-engines-murrine
• gtk2-engines-pixbuf
• sassc
• optipng

Themes:

• MacTahoe GTK Theme: macOS-like GTK theme installed to ~/.themes
• MacTahoe Icon Theme: macOS-like icons installed to ~/.icons
• MacTahoe Cursor Theme: macOS-like cursors installed to ~/.icons
• MacTahoe Wallpapers: Official wallpapers from MacTahoe theme repository
• Display Manager: LightDM/GDM configured to use MacTahoe theme and wallpaper

System Tweaks:

• Dark Mode: Enabled by default
• Window Buttons: macOS-like layout (close button on left)
• Touchpad: Natural scrolling and tap-to-click enabled
• Hot Corners: Disabled by default
• Fonts: Monospace set to Meslo LG S Nerd Font
• Plank Dock: Icon size 48px, window-dodge mode, bottom position
• Animations: Enabled for smooth UI

All themes and settings are automatically applied via gsettings. MacTahoe wallpapers are downloaded from the official theme repository to ~/.local/share/backgrounds/ and one is copied to /usr/share/backgrounds/provision/ for the login screen. You can customize in System Settings > Desktop.

Common Modifications

Add CLI tool - edit scripts/packages.sh:

install_package newtool [debian_name] [arch_name] [brew_name]

Add GUI app - edit scripts/apps.sh:

case "$OS_TYPE" in
    macos) install_cask newapp ;;
    debian) # debian install ;;
    arch) install_aur newapp ;;
esac

Work tools - use INCLUDE_WORK pattern:

if [ "${INCLUDE_WORK:-false}" = true ]; then
    # work-specific installs
fi

Update dotfiles:

# Edit files in config/
./config/link-dotfiles.sh  # Re-symlink

Post-Install

1. exec $SHELL - Reload shell
2. Edit ~/.gitconfig - Set name/email
3. Tmux: Ctrl+a then I - Install plugins
4. Linux (except elementary OS): sudo systemctl enable --now xdm - Enable graphical login
5. elementary OS: Theme changes should apply immediately, logout/login if needed

Gotchas

1. Debian fresh install: Add user to sudo, then logout/login
2. macOS: Install Xcode CLI tools first
3. Arch AUR: Script installs AUR helper if missing
4. XDM changes: Run scripts/update-xdm.sh + restart service (not applicable to elementary OS)
5. DPI changes: Logout/login to apply (not applicable to elementary OS)
6. elementary OS: X11/TWM setup automatically skipped - uses native Pantheon desktop

Prerequisites

• git, curl, sudo access (or root)
• macOS: Xcode CLI Tools
• Debian: build-essential (auto-installed)
• Arch: base-devel (auto-installed)

Design Principles

1. Simple: 4 main scripts, not 20+
2. Fast: Parallel installs where possible
3. Idempotent: Always safe to re-run
4. Self-contained: All configs included
5. Flexible: Skip components with flags
6. Minimal deps: Pure bash
7. Transparent: Read scripts to see what happens

Error Handling

• All scripts: set -euo pipefail
• Installation failures logged but non-fatal for non-critical tools
• Bootstrap validates prerequisites

Testing

• Test on fresh VMs for each OS
• Re-run scripts to validate idempotency
• Scripts runnable standalone for component testing