literate-dotfiles/CLAUDE.md

CLAUDE.md

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

Overview

This is a literate dotfiles repository. All configuration is written in Org-mode files (.org), which are then tangled (extracted) into actual config files placed at their target paths on the filesystem (e.g., ~/.bashrc, ~/.config/doom/config.el).

How Tangling Works

Each .org file contains source code blocks like:

#+begin_src bash :tangle ~/.bashrc :comments both :mkdirp yes
# shell code here
#+end_src

The :tangle <path> header arg specifies the destination file. When tangled from Emacs, the code blocks are extracted and written to those paths.

To tangle a single file (from within Emacs):

M-x org-babel-tangle  (or C-c C-v t)

To tangle all files (from the command line):

emacs --batch --eval "(require 'org)" --eval '(org-babel-tangle-file "file.org")'

Key Conventions

• #+SETUPFILE: ./setup/org-setup-file.org — shared HTML export settings, included at the top of most files
• :noweb yes — some blocks use noweb references like <<get-password(passname="...")>> which calls named blocks from emacs-library-babel.org to fetch passwords from pass
• :tangle-mode (identity #o600) — some sensitive files (e.g., ~/.netrc, ~/.smbcredentials) are tangled with restricted permissions
• :mkdirp yes — automatically creates the target directory if missing
• :comments both — inserts org link comments into the tangled output so you can navigate back to the source

Library of Babel (emacs-library-babel.org)

Defines reusable named blocks:

• get-password — retrieves a secret from pass (the password store)
• pdf2svg — converts PDF figures to SVG/PNG
• addhdr — adds hline to org tables

This file must be loaded in Emacs (via org-babel-lob-ingest) for noweb calls to <<get-password(...)>> to work during tangling.

HTML Documentation (docs/)

The .org files can also be exported to HTML (stored in docs/). The setup/org-setup-file.org configures the HTML theme. Pre-built HTML is already present; regenerate with M-x org-export-dispatch → HTML in Emacs.

File Map

Each .org file corresponds to a tool/topic and tangles to one or more config files:

File	Tangles to
applications.org	~/.config/mimeapps.list, ~/.local/share/applications/*.desktop
bash.org	~/.bashrc, ~/.bash_profile, ~/.profile, ~/.config/readline/inputrc
binaries.org	Scripts in ~/.local/bin/
binaries-private.org	Private/work scripts in ~/.local/bin/
calendar-contact.org	~/.config/vdirsyncer/, ~/.config/khal/, ~/.config/khard/
compositor.org	~/.config/picom/picom.conf
config.org	~/.ssh/config, ~/.XCompose, ~/.config/fontconfig/, ~/.netrc, ~/.smbcredentials, etc.
doom.org	~/.config/doom/config.el, init.el, packages.el
emacs-snippets.org	~/.config/doom/snippets/
git.org	~/.config/git/config, ~/.config/pass-git-helper/
homelab.org	Remote files on homelab via TRAMP (/ssh:thomas@homelab:…)
i3.org	~/.config/i3/config
image.org	~/.config/nsxiv/exec/key-handler
kitty.org	~/.config/kitty/kitty.conf
mail.org	~/.config/isync/, ~/.config/msmtp/, ~/.config/neomutt/
matlab.org	~/.config/matlab/startup.m, ~/.config/matlab/setup.m
music.org	~/.config/mopidy/, ~/.config/ncmpcpp/
polybar.org	~/.config/polybar/config.ini, ~/.config/polybar/scripts/
qutebrowser.org	~/.config/qutebrowser/config.py, ~/.config/qutebrowser/userscripts/
ranger.org	~/.config/ranger/
sxhkd.org	~/.config/sxhkd/sxhkdrc
systemd.org	~/.config/systemd/user/ units and associated scripts in ~/.local/bin/
tablet.org	Xournal++ toolbar, Huion tablet setup scripts
tmux.org	~/.config/tmux/tmux.conf
torrent.org	~/.config/stig/rc, ~/.config/aria2/
vim.org	~/.config/nvim/init.vim
xconfig.org	~/.Xresources, ~/.config/X11/xinitrc, ~/.xprofile
yazi.org	~/.config/yazi/
android.org	Documentation only (no tangle)
backup.org	Documentation only (no tangle)
maintenance.org	Documentation only (no tangle)
router.org	Documentation only (no tangle)
squeezelite.org	Documentation only (no tangle)

Doom Emacs Notes

When modifying doom.org (which tangles init.el or packages.el), after tangling run:

doom sync

Then restart Emacs with SPC q r.