Claude Code for Stow Dotfiles Manager Workflow Tutorial

Managing dotfiles—those hidden configuration files in your home directory that customize your development environment—is a perennial challenge for developers. From .zshrc to .vimrc, .gitconfig to .tmux.conf, these files define your personal workspace. In this tutorial, you’ll learn how to combine Claude Code with GNU Stow to create a powerful, organized, and reproducible dotfiles management system.

Why Stow for Dotfiles?

GNU Stow is a symlink farm manager that originated for managing software packages, but it has become popular in the dotfiles community for its simplicity. Unlike other dotfiles solutions that require complex scripts or specialized tools, Stow uses a declarative approach:

• Organize: Place your config files in a dedicated directory (typically ~/dotfiles/)
• Stow: Run stow to create symlinks from your home directory to the dotfiles repo
• Unstow: Easily remove symlinks when you want to clean up

This approach keeps your dotfiles in a Git repository while making them appear in the right locations automatically.

Setting Up Your Stow-Based Dotfiles Repository

First, let’s create a proper Stow directory structure. Here’s the recommended layout:

~/dotfiles/
├── .zshrc/
│   └── .zshrc
├── .vim/
│   └── init.vim
├── .gitconfig/
│   └── .gitconfig
└── .tmux/
    └── .tmux.conf

Each subdirectory (package) contains the actual files you want to symlink. The key insight is that Stow creates symlinks by mirroring the directory structure—you place .zshrc inside a .zshrc/ folder, and Stow links it to ~/.zshrc.

Creating a Claude Skill for Dotfiles Management

Now let’s build a Claude skill that understands your Stow dotfiles workflow. Create a file called dotfiles-manager.md in your Claude skills directory:

---
name: dotfiles-manager
description: Manage dotfiles using GNU Stow. Install, update, or remove dotfile configurations.
tools: [Read, Write, Bash]
---

# Dotfiles Manager Skill

You help manage dotfiles using GNU Stow. You understand the Stow directory structure where each package is a subdirectory containing the files to symlink.

## Available Actions

When asked to install dotfiles:
1. Run `stow -v -t ~ -d ~/dotfiles <package>` to install a specific package
2. Or run `stow -v -t ~ -d ~/dotfiles -S *` to install all packages

When asked to remove dotfiles:
1. Run `stow -v -t ~ -d ~/dotfiles -D <package>` to remove a specific package

When asked to show status:
1. Run `cd ~/dotfiles && stow -v --adopt` to see what would change
2. Run `ls -la ~ | grep -E '^\.'` to see current dotfile symlinks

This skill gives Claude Code context about your dotfiles structure and the commands needed to manage them.

Practical Workflow Examples

Installing a New Dotfile

When you want to add a new configuration to your dotfiles:

1. Create the file in your Stow directory:

   mkdir -p ~/dotfiles/.newrc
   cp ~/.newrc ~/dotfiles/.newrc/.newrc
   

2. Tell Claude to install it:

   Can you stow the .newrc package to my home directory?
   

Claude will run:

stow -v -t ~ -d ~/dotfiles .newrc

Updating Dotfiles Across Machines

A common workflow is to update your dotfiles on one machine, push to Git, then pull and apply on another:

1. On machine A: Make changes, commit, push

   cd ~/dotfiles
   git add . && git commit -m "Update vim config"
   git push origin main
   

2. On machine B: Pull and Stow

   cd ~/dotfiles
   git pull origin main
   stow -v -t ~ -S *  # Re-stow all packages
   

Your Claude skill can handle this too—just ask:

Pull my latest dotfiles from GitHub and install them

Advanced: Stow with Git Submodules

For more complex setups, you might want to include other repositories as part of your dotfiles. Git submodules work well with Stow:

cd ~/dotfiles
git submodule add git@github.com:username/vim-plug.git .vim/plugged/vim-plug

Then when you Stow your .vim directory, the submodule contents are included.

Best Practices for Stow Dotfiles

1. Use descriptive package names: Name directories after the tool (.zshrc/, .vim/) not after the file type
2. Keep sensitive data separate: Never store secrets in your dotfiles repository; use tools like pass or environment variables
3. Version control everything: Your dotfiles are code—commit changes, write meaningful messages, use branches for experimental configs
4. Test before unstowing: Always check what will change with stow --adopt --simulate before running destructive operations

Integrating with Your Daily Workflow

The real power comes from integrating your dotfiles management into your daily Claude Code interactions. Here are some prompts to try:

• “What dotfiles packages are currently stowed?”
• “Add my new alias to .zshrc and stow it”
• “Show me what changed in my dotfiles since last week”
• “Backup my current dotfiles configuration”

Troubleshooting Common Stow Issues

“File exists” errors: Stow won’t overwrite existing files. Remove the target file first or use the --adopt flag to adopt existing files.

“No such file or directory” errors: Ensure your Stow directory structure is correct—each package must be a subdirectory containing the files.

Symlinks pointing wrong: Use ls -la ~ | grep dotfiles to verify symlink targets are correct.

Conclusion

Combining Claude Code with GNU Stow gives you a powerful, reproducible system for managing configuration files. The declarative nature of Stow means your dotfiles remain organized and version-controlled, while Claude Code provides an intelligent interface to interact with them naturally. Start with a simple setup, commit regularly, and gradually add more configurations as you need them.

Your dotfiles are personal—they should evolve with your workflow. With Stow and Claude Code, managing that evolution becomes significantly easier.