agentree

agentree 🌳🤖

Create and manage isolated Git worktrees for AI coding agents.

Overview

agentree simplifies working with multiple AI coding agents (like Cursor, Claude Code, and GitHub Copilot) by creating isolated Git worktrees. Each agent gets its own branch and directory, allowing concurrent work without conflicts.

Why agentree?

When working with AI coding assistants, you often need to:

• Create isolated environments for different tasks
• Quickly switch between multiple concurrent experiments
• Maintain clean separation between AI-generated changes
• Easily clean up after experiments

agentree automates this workflow with a single command.

Installation

Homebrew (Recommended)

brew tap AryaLabsHQ/tap
brew install agentree

Download Pre-built Binary

Download the latest release for your platform from the releases page.

Build from Source

git clone https://github.com/AryaLabsHQ/agentree.git
cd agentree
make build
make install

Usage

Quick Start

# Interactive mode (recommended) - wizard guides you through all options
agentree -i

# Or specify a branch name directly
agentree -b feature-x

That's it! agentree will:

• Create a new branch prefixed with agent/ (e.g., agent/feature-x)
• Set up an isolated worktree in ../myrepo-worktrees/
• Intelligently discover and copy environment files based on .gitignore
• Copy AI tool configs (.claude/settings.local.json, .cursorrules, etc.)
• Run setup commands (auto-detected: npm/pnpm/yarn install, etc.)
• Switch you to the new worktree directory

Common Options

# Skip environment copying and setup (use -e=false -s=false)
agentree -b feature-x -e=false -s=false

# Push to GitHub after creation  
agentree -b feature-x -p

# Push and create a PR (Note: PRs are usually created after making changes)
agentree -b feature-x -r

Advanced Usage

# Create from specific base branch
agentree -b feature-x -f main

# Custom destination
agentree -b feature-x -d ~/projects/custom-dir

# Run custom post-create scripts
agentree -b feature-x -S "pnpm install --frozen-lockfile" -S "pnpm test"

# Individual flags:
# -p    Push to origin after creation
# -e    Copy .env and .dev.vars files
# -s    Auto-detect and run setup (pnpm install, npm install, etc.)

Remove a worktree

# Remove by branch name
agentree rm agent/feature-x

# Remove by path
agentree rm ../myrepo-worktrees/agent-feature-x

# Force removal (no confirmation)
agentree rm agent/feature-x -y

# Also delete the branch
agentree rm agent/feature-x -R

Features

• Interactive wizard: Use -i flag for a guided setup that prompts for all options
• Quick worktree creation: Automatically prefixes branches with agent/ for organization
• Easy cleanup: Remove worktrees and optionally delete branches
• GitHub integration: Push branches and create PRs directly
• Flexible paths: Custom destination directories or automatic organization
• Environment copying: Optionally copy .env and .dev.vars files to new worktrees
• Auto-setup: Automatically detect and run package manager install/build commands
• Configurable: Project and global configuration for custom post-create scripts
• Cross-platform: Works on macOS, Linux, and Windows

Configuration

Project Configuration (.agentreerc)

Create a .agentreerc file in your project root to define custom post-create scripts:

# .agentreerc
POST_CREATE_SCRIPTS=(
  "pnpm install"
  "pnpm build"
  "cp .env.example .env"
)

Global Configuration (~/.config/agentree/config)

Create a global config for user-wide defaults:

# ~/.config/agentree/config
# Override auto-detected scripts
PNPM_SETUP="pnpm install --frozen-lockfile && pnpm build"
NPM_SETUP="npm ci && npm run build"

# Default when no package manager detected
DEFAULT_POST_CREATE="echo 'Ready to work!'"

Auto-Detection

When using -s flag, agentree automatically detects and runs appropriate setup commands:

• pnpm: pnpm install + pnpm build (if build script exists)
• npm: npm install + npm run build (if build script exists)
• yarn: yarn install + yarn build (if build script exists)
• cargo: cargo build
• go: go mod download
• pip: pip install -r requirements.txt
• bundler: bundle install

Examples

# AI agent working on authentication
agentree -b auth-system

# Interactive mode to choose base branch
agentree -i

# AI agent fixing bugs, push when ready
agentree -b bugfix-123 -p

# Quick experiment, create PR immediately
agentree -b experiment-ml -r

# Cleanup after work is merged
agentree rm agent/auth-system -R

Shell Completion

agentree supports tab completion for commands, flags, branch names, and worktree names.

Bash

# Add to ~/.bashrc or ~/.bash_profile:
source <(agentree completion bash)

Zsh

# Add to ~/.zshrc:
source <(agentree completion zsh)

# Or for oh-my-zsh users, add to completions directory:
agentree completion zsh > ~/.oh-my-zsh/completions/_agentree

Fish

# Add to ~/.config/fish/completions/:
agentree completion fish > ~/.config/fish/completions/agentree.fish

PowerShell

# Add to your PowerShell profile:
agentree completion powershell | Out-String | Invoke-Expression

Development

# Clone the repository
git clone https://github.com/AryaLabsHQ/agentree.git
cd agentree

# Run tests
make test

# Build binary
make build

# Run locally
make run

Version History

• v1.0+: Complete rewrite in Go with interactive mode, better performance, and cross-platform support
• v0.1: Original bash implementation (available as agentree-v0.1.sh for reference)

Why the rewrite?

The original bash script served well but had limitations:

• Platform-specific issues (especially on Windows)
• Limited testing capabilities
• Difficult to add complex features like interactive mode
• No proper dependency management

The Go version provides:

• Cross-platform compatibility
• Better performance
• Comprehensive test coverage
• Interactive TUI with branch selection
• Easier distribution via homebrew
• Type safety and better error handling

Requirements

• Git 2.5+ (for worktree support)
• Optional: gh CLI for GitHub PR creation

License

MIT