dotfiles

Personal dotfiles managed with chezmoi.

Quick start

Fresh machine (one-liner):

sh -c "$(curl -fsLS get.chezmoi.io)" -- \
  init --apply bkahlert --source ~/.local/share/chezmoi

Existing machine:

brew install chezmoi
chezmoi init --apply bkahlert

How it works

• chezmoi manages dotfiles — copies files to $HOME (no symlinks). Source state lives in home/ (via .chezmoiroot).
• ZDOTDIR — zsh config lives in ~/.config/zsh/, only ~/.zshenv remains in $HOME.
• Sheldon — zsh plugin manager (TOML config, Rust-based).
• Starship — cross-shell prompt (TOML config, Rust-based).
• Autoloaded functions — zsh-specific functions are files in functions/, loaded on first call.
• Standalone scripts — shell-agnostic utilities under home/dot_local/exact_bin/ mirror ~/.local/bin exactly: removing a script from the repo removes it from the target.
• AI assistant configs — ~/.claude/, ~/.gemini/, and ~/.config/agents/ are tracked so prompt rules and slash commands stay in sync across machines.

Making changes

Dotfiles (chezmoi)

chezmoi edit ~/.gitconfig         # edit a managed file
chezmoi diff                      # preview pending changes
chezmoi apply                     # apply changes to $HOME
chezmoi add ~/.config/foo/config  # start managing a new file

See chezmoi daily operations.

Zsh modules

Add a new module — create a numbered .zsh file in conf.d/:

chezmoi edit ~/.config/zsh/conf.d/10-mytool.zsh

Add a new function — create a file in functions/ named after the function. The file contains only the function body (no funcname() { wrapper):

chezmoi edit ~/.config/zsh/functions/myfunction

# Example: functions/greet
echo "Hello, ${1:-world}!"

Plugins (Sheldon)

Edit the plugin list:

chezmoi edit ~/.config/sheldon/plugins.toml

Add a plugin by adding a [plugins.<name>] section:

[plugins.my-plugin]
github = "author/repo"

Update all plugins:

sheldon lock --update

See Sheldon documentation.

Prompt (Starship)

Edit the prompt configuration:

chezmoi edit ~/.config/starship.toml

Changes take effect on the next prompt render (no restart needed).

See Starship configuration.

Ghostty

Edit the terminal configuration:

chezmoi edit ~/.config/ghostty/config

Live reload: press Cmd+Shift+, (macOS) or Ctrl+Shift+, (Linux).

See Ghostty configuration reference.

Zsh load order

~/.zshenv                       → sets ZDOTDIR
~/.config/zsh/.zprofile         → Homebrew shellenv
~/.config/zsh/.zshrc            → autoloads functions, sources conf.d/*
  00-context.zsh.tmpl           → stamps $DOTFILES_CONTEXT
  01–07                         → core (options, history, completions,
                                  keybindings, prompt, aliases, plugins)
  08-print.zsh                  → printf helpers
  10-*.zsh                      → tool modules
  20-claude.zsh                 → Claude CLI
  conf.d/$DOTFILES_CONTEXT/     → context-specific overrides (sourced last)

SSH keys (KeePassXC)

Personal SSH keys (github, etc.) live in iCloud Drive's Vault directory. On chezmoi apply, .chezmoiscripts/run_onchange_after_dump-ssh-from-kdbx.tmpl reads the vault (prompting for the master password via a macOS dialog) and materializes ~/.ssh/conf.d/*.conf + *.pub files; the actual private keys are pushed live into the launchd ssh-agent (SSH_AUTH_SOCK) by KeePassXC's own SSH Agent integration when the database is unlocked.

KeePassXC is installed via the Brewfile, but its SSH Agent integration is an app preference chezmoi can't manage — set it up once per machine:

1. Open KeePassXC and unlock your kdbx file(s).
2. Settings → SSH Agent → check "Enable SSH Agent integration", then fully quit and reopen KeePassXC (the per-entry tab below only appears after a restart).
3. For each key entry, edit it → SSH Agent tab → check "Add key to agent when database is opened/unlocked" (usually already set from the kdbx template).

Testing in a container

Build and test with Podman:

make build      # build Fedora + Ghostty + VNC image
make validate   # apply dotfiles + verify zsh starts
make run        # start container with VNC on :5901
make vnc        # open VNC viewer
make stop       # stop the container
make clean      # remove the image

Repairing the startup LaunchAgent

The ~/.startup script runs at login via a LaunchAgent. If it stops working:

# Re-run the chezmoi setup script
chezmoi apply --force

Or manually recreate:

launchctl unload ~/Library/LaunchAgents/com.user.startup.plist 2>/dev/null
chezmoi state delete-bucket --bucket=scriptState
chezmoi apply