Installation

A Note on a Safe, Conflict-Free Installation

This project uses a git bare repository to manage your agents, a powerful technique for managing dotfiles. To ensure this system never conflicts with your own files, the installation uses Git's sparse-checkout feature. This guarantees that the setup will only ever affect the ~/.claude directory, making it completely safe.

1. Clone the Repository

First, clone this repository to a hidden "bare" repository in your home directory.

git clone --bare https://github.com/iamrichardd/dotagents.git $HOME/.dotagents.git

2. Set Up the Alias

Add the following alias to your shell configuration file (e.g., ~/.zshrc, ~/.bashrc). This gives you a convenient claude-agents command.

alias dotagents="git --git-dir=$HOME/.dotagents.git/ --work-tree=$HOME"

After adding the alias, restart your shell or source your configuration file.

3. Check Out the Agents

Run the following commands from anywhere in your terminal. This will configure your local repository to only track the `agents` directory and then pull those files into your `~/.claude` directory.

cd ~/
dotagents sparse-checkout init --no-cone
dotagents sparse-checkout set .claude/agents
dotagents sparse-checkout reapply
dotagents checkout

4. Configure Git Exclude Patterns (Critical Step)

Create the exclude file with the proper patterns:

cat > ~/.dotagents.git/info/exclude << 'EOF'
# Exclude everything in home directory by default
*

# But include .claude directory and its contents  
!/.claude/
!/.claude/agents/
!/.claude/agents/**
EOF

Verify the setup works:

# This should now show only your agent files, not your entire home directory
dotagents status

You should see either "nothing to commit, working tree clean" or only files from your ~/.claude/agents/ directory.

Important: Handling Existing Configurations

If you already have custom agents in ~/.claude/agents, these steps will help you perform a safe merge.

1. Back Up Your Existing Agents:

   [ -d ~/.claude/agents ] && mv ~/.claude/agents ~/.claude/agents.backup

2. Run the Checkout Command:

   The checkout command from the previous step should now succeed. If it fails, you may need to force it: dotagents checkout -f.

3. Merge Your Backup:

   [ -d ~/.claude/agents.backup ] && mv ~/.claude/agents.backup/* ~/.claude/agents/

4. Clean Up:

   [ -d ~/.claude/agents.backup ] && rm -rf ~/.claude/agents.backup

Updating the Agents

To pull the latest agents and updates from the repository, run:

dotagents pull

Troubleshooting

Problem: dotagents status shows thousands of home directory files

If you see your entire home directory listed in dotagents status, the Git exclude patterns weren't configured properly.

Solution: Create the exclude file manually:

cat > ~/.dotagents.git/info/exclude << 'EOF'
*
!/.claude/
!/.claude/agents/
!/.claude/agents/**
EOF

Then test again:

dotagents status

You should now see only your agent files, not your entire home directory.