---

name: dotfiles description: Expert in managing dotfiles using GNU Stow. Use when working with shell configs (zsh, oh-my-zsh, bash), editors (neovim, nvim, vscode), terminal tools (tmux, ghostty), prompts (starship), CLI replacements (eza, bat, fzf, zoxide, lazygit), keyboard (karabiner), secrets (bitwarden-cli), or any configuration in ~/.config. Covers stow symlink management, lazy loading patterns, Catppuccin theming, security best practices, and this specific dotfiles repository structure. user-invocable: false

Dotfiles Management Skill

Expert guidance for managing this cross-platform dotfiles repository using GNU Stow.

Quick Reference

Critical Repository Pattern

The .stowrc file configures:

• --dir=./dotfiles - stow source directory
• --target=~/ - symlinks created in home
• --dotfiles - dot- prefix converts to .

Example: dot-zshrc becomes ~/.zshrc

Directory Structure

Copy/Users/raphael/Projects/dotfiles/
├── .stowrc                    # Stow configuration
├── CLAUDE.md                  # Claude Code project instructions
├── setup.sh                   # Main installation script
├── homebrew/
│   └── Brewfile               # Package manifest
├── dotfiles/                  # Stow source directory
│   ├── dot-zshrc              # -> ~/.zshrc
│   ├── dot-zprofile           # -> ~/.zprofile
│   ├── dot-config/            # -> ~/.config/
│   │   ├── nvim/              # Neovim (lazy.nvim)
│   │   ├── tmux/              # Tmux + TPM
│   │   ├── starship/          # Starship prompt
│   │   ├── ghostty/           # Ghostty terminal
│   │   ├── zsh/               # Zsh aliases
│   │   ├── bat/               # bat config
│   │   ├── lazygit/           # lazygit config
│   │   ├── karabiner/         # Keyboard mods
│   │   └── nushell/           # Nushell config
│   ├── dot-claude/            # -> ~/.claude/
│   │   ├── settings.json      # Claude Code settings
│   │   ├── statusline.sh      # Token usage tracker
│   │   ├── hooks/             # PreToolUse hooks
│   │   └── skills/            # Claude Code skills
│   └── dot-local/
│       └── bin/               # Utility scripts
└── scripts/                   # Installation helpers

Essential Commands

Copy# Apply configuration changes
stow .                           # Create/update symlinks
stow -R .                        # Force restow (unlink + relink)
stow -D .                        # Remove all symlinks
stow -n .                        # Dry run (show what would happen)

# Reload configurations
source ~/.zshrc                  # Shell changes
tmux source-file ~/.config/tmux/tmux.conf  # Tmux changes

# Neovim
:Lazy sync                       # Update plugins
:Mason                           # Manage LSP servers
:checkhealth                     # Diagnose issues

# Tmux plugins (TPM)
prefix + I                       # Install plugins
prefix + U                       # Update plugins

# Package management
brew bundle --file=homebrew/Brewfile  # Install all packages

Theme Consistency

Key Colors (Macchiato):

• Base: #24273a
• Text: #cad3f5
• Blue: #8aadf4
• Green: #a6da95
• Red: #ed8796

Performance Patterns

Version managers (jenv, pyenv, nvm) are lazy-loaded to speed up shell startup:

Copy# Pattern used in dot-zshrc
if [[ -d "$HOME/.jenv" ]]; then
  jenv() {
    unset -f jenv
    export PATH="$HOME/.jenv/bin:$PATH"
    _evalcache jenv init -
    jenv "$@"
  }
fi

evalcache Plugin

Expensive command outputs are cached using the evalcache oh-my-zsh plugin:

Copy_evalcache zoxide init zsh --cmd cd
_evalcache gh copilot alias -- zsh

Benchmarking

Copyzsh-time      # Quick timing: time zsh -i -c exit
zsh-debug     # Detailed profiling with zprof

Security Best Practices

These should NEVER be in the repository:

• Passwords and API keys
• SSH keys (~/.ssh/)
• GPG keys (~/.gnupg/)
• Session tokens

Environment Variables

Load secrets from secure sources:

Copy# In dot-zshrc - loads ~/.env if it exists
if [[ -f ~/.env ]]; then
    while IFS= read -r line || [[ -n "$line" ]]; do
        if [[ -n "$line" && ! "$line" =~ ^[[:space:]]*# ]]; then
            export "$line"
        fi
    done < ~/.env
fi

Bitwarden CLI Integration

Use Bitwarden CLI for secure secret access:

Copybw-unlock              # Unlock vault, export BW_SESSION
bwp "GitHub Token"     # Get password by name
bwc "API Key"          # Copy to clipboard

See TOOLS.md for full Bitwarden CLI setup.

File Permissions

Sensitive files should have restricted permissions:

Copychmod 400 ~/.ssh/id_*
chmod 600 ~/.env

File Modification Workflow

1. Apply changes with stow

   Copystow .
   

2. Reload the relevant configuration

   Copysource ~/.zshrc                    # For shell changes
   tmux source ~/.config/tmux/tmux.conf  # For tmux
   # Neovim auto-reloads on file save
   

3. Test the changes

4. Commit when satisfied

   Copygit add -A && git commit -m "feat: description"
   

Adding New Configurations

Adding a New Dotfile

1. Create the file with dot- prefix:

   Copy# For ~/.newconfig
   touch dotfiles/dot-newconfig
   
   # For ~/.config/app/config
   mkdir -p dotfiles/dot-config/app
   touch dotfiles/dot-config/app/config
   

2. Run stow . to create symlinks

3. Verify with ls -la ~/ | grep newconfig

Adding to Brewfile

Copy# Add formula
echo 'brew "package-name"' >> homebrew/Brewfile

# Add cask
echo 'cask "app-name"' >> homebrew/Brewfile

# Install
brew bundle --file=homebrew/Brewfile

Cross-Platform Notes

The repository supports both platforms with conditional logic:

Copy# In dot-zshrc
if [[ -d /opt/homebrew/bin ]]; then
  export PATH=/opt/homebrew/bin:$PATH
fi

Platform-Specific Paths

When to Read Reference Files

Read ZSH.md when:

• Adding shell aliases or functions
• Configuring Oh-My-Zsh plugins
• Troubleshooting shell startup

Read NEOVIM.md when:

• Adding or configuring plugins
• Setting up LSP for a language
• Customizing keymaps

Read TMUX.md when:

• Modifying keybindings
• Adding or updating plugins
• Configuring status bar

Read GHOSTTY.md when:

• Changing terminal appearance
• Setting up shell integration
• Customizing keybindings

Read STOW.md when:

• Understanding how symlinks work
• Resolving stow conflicts
• Adding new configuration packages

Read TOOLS.md when:

• Configuring CLI tool replacements
• Setting up Bitwarden CLI
• Customizing fzf, bat, eza, etc.

Read TROUBLESHOOTING.md when:

• Shell startup is slow
• Plugins aren't loading
• Symlinks aren't working
• Theme colors are wrong