dotfiles/CLAUDE.md

CLAUDE.md

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

What this repo is

Personal dotfiles managed with chezmoi. This directory (~/.local/share/chezmoi) is chezmoi's source directory — files here use chezmoi's naming conventions and are rendered/installed into $HOME on the target machine, they are not consumed directly from this path.

Use the chezmoi skill (.claude/skills/chezmoi-skill/SKILL.md) for any work in this repo. It covers chezmoi's source-file naming conventions (dot_, private_, executable_, .tmpl), machine-specific templating patterns, the required chezmoi apply --refresh-externals --force flags, .chezmoiremove/.chezmoiexternal.toml, and troubleshooting — invoke it rather than re-deriving this from scratch.

Commands

Preview and apply changes (run from anywhere; chezmoi finds the source dir automatically):

chezmoi diff                                  # preview pending changes before applying
chezmoi apply --refresh-externals --force     # apply — always use both flags (force avoids interactive prompts Claude can't answer)
chezmoi cat <file>                            # preview a rendered template's output
chezmoi execute-template '{{ .chezmoi.os }}'  # test a template snippet in isolation
chezmoi re-add <file>                         # pull an edited target file back into the source dir
chezmoi status                                # what's pending

Syncing to git (per README.md):

chezmoi cd            # cd into the source dir (this repo)
git add --all && git commit && git push
chezmoi update        # pull + apply on another machine

There is no build, lint, or test suite — this is a config repo. "Testing" a change means chezmoi diff/chezmoi cat to check rendering, then chezmoi apply --refresh-externals --force and exercising the shell/tool it affects.

Architecture

• run_onchange_before_NN_*.sh — idempotent setup scripts chezmoi re-runs whenever their content hash changes, in numeric order (0 installs apt packages, 1 sets zsh as default shell and installs antidote, 20+ install individual tools: fzf, diff-so-fancy, vim-plug, tmux plugin manager, lazygit, fonts, difftastic, nbdime). New machine-setup steps should follow this pattern: a numbered run_onchange_before_*.sh with set -euo pipefail and an existence check so re-runs are no-ops.
• .chezmoi.toml.tmpl — chezmoi's own config template; prompts once for github_email and enables autoCommit/autoPush on chezmoi apply (so applying on a configured machine also commits/pushes to this repo — be aware of that when testing changes there).
• .commit_message.tmpl — template chezmoi uses to prompt for the commit message when autoCommit fires.
• Shell startup chain: dot_zshrc sources bin/term-background (must run before the p10k instant-prompt block, since it reads the tty for OSC 11 background detection) → p10k instant prompt → ~/.environment(dot_environment) + optional ~/.environment.local → ~/.aliases (dot_aliases) + optional ~/.aliases.local → antidote plugin load (plugin list in dot_zsh_plugins.txt) → ~/.p10k.zsh. The .local files are gitignored, host-specific overrides — never add machine-specific values directly to the tracked files.
• dot_gitconfig.tmpl — templated on .github_email; wires up diff-so-fancy/difftastic as pagers and nbdime for Jupyter notebook diffing. ~/.gitconfig.local (untracked) is included for machine-specific overrides.
• private_dot_config/ → installs to ~/.config/ with restrictive permissions (nvim, matplotlib styles, fontconfig).
• bin/ → installs to ~/bin/; executable_term-background detects terminal light/dark background via OSC 11 for theme-matching in nvim etc.
• .chezmoiignore lists source-repo-only paths (README.md, .claude, .codex, .agents) that chezmoi should never install to $HOME.