# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview This is `dots`, a dotfiles manager that combines Jinja2 templating with GNU Stow for symlink management. It enables maintaining a single set of dotfiles across multiple machines by using context-driven templating. ## Core Architecture ### Three-Phase Process 1. **Compile**: Templates in `dots/` (files ending in `.j2`) are rendered using Jinja2 with context from `context.json`, output to `.compiled_dotfiles/` 2. **Stow**: Compiled packages are symlinked to the target directory (default: `$HOME`) using GNU Stow 3. **Clean**: Removes symlinks and clears `.compiled_dotfiles/` ### Directory Structure - `dots/`: Source dotfiles organized as Stow packages (e.g., `nvim/`, `git/`, `sway/`) - `.compiled_dotfiles/`: Generated output after template compilation (git-ignored) - `dots_manager/`: Python package implementing the CLI tool - `context.json`: Configuration variables organized by platform and system ### Context System `context.json` structure: ```json { "_global": { /* shared across all systems */ }, "osx": { "_default": { /* defaults for all macOS systems */ }, "system_name": { /* specific system config */ } }, "linux": { /* similar structure */ } } ``` Context merging: `_global` → `platform._default` → `platform.system_name` Templates access context variables directly: `{{ env.EDITOR }}`, `{{ window_manager.key.sup }}` ### Key Modules - `cli.py`: Entry point, orchestrates compile/stow/clean operations - `config.py`: Loads context, detects platform/system via helper scripts in `dots/home/scripts/` - `template.py`: Jinja2 rendering with parallel processing - `stow.py`: Wraps GNU Stow commands for symlinking - `utils.py`: Parallelization and dictionary merging utilities ## Common Commands ### Setup ```bash python -m venv .venv source .venv/bin/activate pip install -e . ``` ### Basic Usage ```bash # Compile templates only dots --compile # Compile and stow dots --compile --stow # Remove symlinks and clean compiled files dots --clean # Full cycle with verbose output dots --clean --compile --stow --verbose ``` ### Development/Testing ```bash # Test with custom context file dots --compile --context ./test_context.json # Dry-run compilation (templates rendered but not stowed) dots --compile --output /tmp/test_dots # Override platform/system detection dots --compile --platform linux --system-name test-machine ``` ## Important Implementation Details - Template files must have `.j2` extension; compiled output strips this extension - Jinja2 uses `StrictUndefined` - missing context variables will error during compilation - File permissions are preserved from templates to compiled files - Stow operations use `--no-folding` to prevent directory folding - Platform detection uses `$OSTYPE`; system name uses hostname or macOS `computername` - Template compilation is parallelized (workers = CPU count × 2) ## When Working with Templates - Templates are in `dots/` as `//.j2` - After compilation, they appear in `.compiled_dotfiles///` (no `.j2`) - Test context changes by running `dots --compile` and checking `.compiled_dotfiles/` - Never edit files in `.compiled_dotfiles/` directly - they are regenerated on compile