dotfiles/CLAUDE.md

CLAUDE.md

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

What this is

Personal dotfiles managed by Bombadil. Source config files live at the top level of this repo. Bombadil renders them (substituting template variables) into .dots/, then symlinks the rendered files into $HOME / ~/.config according to bombadil.toml.

Applying changes

After editing any source file, re-render and re-link:

bombadil link              # render templates -> .dots/ and refresh symlinks
bombadil link -p dark      # apply the "dark" profile
bombadil link -p light     # apply the "light" profile

Edits do not take effect until bombadil link is run. The repo is registered globally via ~/.config/bombadil.toml (a symlink to bombadil.toml here, created once by bombadil install).

Key conventions

• Never edit .dots/. It is Bombadil's generated output (not tracked by git) and is overwritten on every bombadil link. Edit the source files at the repo root instead.
• bombadil.toml is the source of truth for what gets linked where. Adding a new config means: add the file at the repo root, then add a [settings.dots] entry mapping source (relative to repo) to target (relative to $HOME).
• Templating: files may contain {{var}} placeholders substituted from the vars files. The active set is vars = ["dark.toml", "vars.toml"] plus whatever profile is selected. vars.toml holds identity (email, name, signing_key). dark.toml / light.toml are profile-specific theme variables (alacritty_theme, helix_theme, zellij_theme, bat_theme, theme). Templated files currently include alacritty/alacritty.toml, helix/config.toml, zellij/config.kdl, gitconfig, and bat/config — switching theme retints all apps at once via the profile.

zsh layout

• zshenv.zsh → ~/.zshenv (env vars, editor detection), zshrc.zsh → ~/.zshrc (interactive setup).
• zshrc.zsh sources every file in ~/.config/zsh.d/* (linked from zsh.d/) then every file in ~/.config/aliases.d/* (linked from aliases.d/). Each file is a self-contained conf.d-style snippet for one tool (e.g. zsh.d/git.zsh, aliases.d/cargo.zsh). Add a tool by dropping a new .zsh file in the matching directory — no central registration needed.
• Machine-specific overrides are sourced if present and are intentionally not in this repo: ~/.zshenv.local, ~/.zshrc.local, ~/.aliases.local.
• Tool integrations guard on availability with if (( $+commands[tool] )); then ... — follow this pattern so configs degrade gracefully on machines lacking a tool. The prompt (zsh.d/prompt.zsh) falls back starship → p10k → manjaro.

Submodules

alacritty/themes (and a legacy alacritty-theme) are git submodules pointing at the upstream alacritty color-theme collection. Run git submodule update --init after cloning.