# CLAUDE.md

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

This is a personal dotfiles repository targeting macOS (Apple Silicon + Intel) and Arch Linux. It is installed by symlinking config directories/files from the repo into `$HOME`, so files here are live configs — editing them changes the running system.

## Installation & setup

Setup is platform-specific and runs from the repo root:

- **macOS:** `./setup_mac.sh` — brews dependencies, creates a `neovim` virtualenv, then calls `./clone_and_link_mac.sh`. Uses GNU coreutils' `gln` (not `ln`), so coreutils must be installed first.
- **Arch:** `./setup_arch.sh` — pacman deps, then `./clone_and_link.sh` + `./copy_fonts_arch.sh`.
- `clone_and_link*.sh` create the symlinks (`~/.zsh`, `~/.zshrc`, `~/.tmux`, `~/.tmux.conf`, `~/.config/nvim`, `~/.config/alacritty`, virtualenvwrapper hooks). `link_config.sh` is a simpler standalone variant.
- `general_setup.sh` switches the login shell to zsh and triggers plugin installs.

## Platform-specific config via `.example` templates

The most important repo-wide convention: platform variants live as `.example` files and the active file is a symlink/copy produced at setup time. The setup scripts loop over files matching `zsh/.*_mac.example`, `tmux/.*_arch.example`, etc., and link/copy each to the name with the `_<platform>.example` suffix stripped.

Practical rule: **edit the `.example` source, not the generated symlink target.** The unsuffixed active files are git-ignored (see each subdir's `.gitignore`). Templates that are copied (not symlinked) at setup — `nvim/scheme.vim.template` → `scheme.vim`, `.config/alacritty/schemes.yml.template` → `schemes.yml` — are also git-ignored once activated.

## Component architecture

- **zsh** (`zsh/.zshrc`): Powerlevel10k instant prompt + [antidote](https://github.com/mattmc3/antidote) plugin manager (plugin list in `zsh/.zsh_plugins.txt`). `.zshrc` sources optional layered configs if present: `.powerline_config`, `.user_config`, `.virtual_env_config.zsh`, `.mac_config.zsh`, `.local_config`. `update_dotfiles()` auto-`git pull`s this repo in the background on every shell start. Machine-local overrides belong in `.local_config` (not committed).
- **nvim** (`nvim/init.vim`): [vim-plug](https://github.com/junegunn/vim-plug), auto-bootstrapped on first launch (`:PlugInstall`). Python provider points at the `~/python-envs/neovim` virtualenv on Apple Silicon. `colors/` holds a large bundled colorscheme collection.
- **tmux** (`tmux/.tmux.conf`): TPM-style `plugins/`. `tmux/tmux_attach.sh` is an attach helper.
- **alacritty** (`.config/alacritty/`): active theme selected via the `import = [...]` line in `alacritty.toml`.
- **gitconfig** (`gitconfig/gitconfig`): identity/behavior split by remote host using `includeIf "hasconfig:remote.*.url:..."` — `github`, `fhms` (fh-muenster), `murgi`, and `sit` (Fraunhofer) each load their own `*.gitconfig`. Change per-context email/signing in the matching include file, not the base config.

## Light/dark theme switching

`.config/alacritty/color_switcher.py` toggles light/dark across the terminal **and** nvim in one shot: it rewrites the `import` line in `alacritty.toml` (`solarized_light.toml` ↔ `dark_mode.toml`) and the `background`/`colorscheme` lines in `~/.config/nvim/scheme.vim`. Keep the regex-matched line formats in those files intact when editing them by hand. `screenshot_mode.py` is a related toggle.

## Maintenance

- `./update_mac.sh` — macOS update runner. Default (no args) runs `--brew-update --cleanup --diagnostics --update-others`; other flags: `--system-update`, `--permission-fix` (strips Caskroom/App quarantine xattrs). Run `./update_mac.sh --help` for the list. `--update-others` also runs `claude --update`.
- `brew_autoupdate` — sets up scheduled brew auto-updates.
