AGENTS.md

This file provides guidance to AI Agents 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 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 pulls this repo in the background on every shell start. Machine-local overrides belong in .local_config (not committed).
nvim (nvim/init.vim): 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 and Codex --update.
brew_autoupdate — sets up scheduled brew auto-updates.

3.8 KiB Raw Permalink Blame History