Git Worktrees

What are Git Worktrees?

Git worktrees allow you to have multiple branches checked out at the same time, each in its own directory. This is useful for:

• Code Reviews - Review PRs without stashing your work
• Quick Fixes - Make hotfixes while working on features
• Comparison - Compare implementations across branches
• Parallel Development - Work on multiple features simultaneously
• AI Agents - Run Claude Code, Codex, or other TUI agents in isolated environments

Prerequisites

Your project must be a Git repository. Worktrees work best with bare repositories or standard clones.

Worktree Storage Locations

Agentastic supports three storage locations for worktrees. Configure this in Settings > Agents.

Location	Path Pattern	Best For
Inside Repo	repo/.worktree/feature-x	Self-contained projects, gitignore'd worktrees
Adjacent (Default)	repo-worktrees/feature-x	Clean separation, easy navigation
Global	~/worktrees/repo/feature-x	Centralized management across projects

Inside Repo

Worktrees are stored in a .worktree/ folder inside your repository.

Pros:

• Self-contained - everything lives in one directory
• Easy to find - worktrees are next to your code
• Works well with project-scoped tools

Cons:

• Increases apparent repo size (though not in git history)
• Must add .worktree/ to .gitignore
• Can clutter project root

Adjacent to Repo (Default)

Worktrees are stored in a sibling folder named {repo}-worktrees/.

Pros:

• Keeps main repo clean
• Easy to see all worktrees at a glance
• Simple cleanup - delete the -worktrees folder

Cons:

• Creates sibling directories
• May clutter parent folder with many projects

Global Location

All worktrees are stored in a central location like ~/worktrees/.

Pros:

• Centralized management across all projects
• Consistent location for scripts and automation
• Easy to set disk quotas or backup policies

Cons:

• Disconnected from project - harder to navigate
• Requires remembering the global path
• May be confusing with many projects

Creating a Worktree

From Settings

1. Open Settings (Cmd+,)
2. Go to Agents
3. Click Create Agent
4. Choose a branch and destination folder

From Command Line

You can also create worktrees via the integrated terminal:

git worktree add ../my-feature feature-branch

This creates a new worktree at ../my-feature checking out feature-branch.

Switching Worktrees

Using Keyboard Shortcuts

Action	Shortcut
Next Agent	Cmd+Option+Down
Previous Agent	Cmd+Option+Up

From Settings

1. Open Settings > Agents
2. Click on an agent to switch to it

From Command Palette

1. Open Command Palette (Cmd+Shift+P)
2. Type "worktree"
3. Select Switch to Worktree
4. Choose the target worktree

Managing Worktrees

Viewing All Worktrees

1. Open Settings > Agents
2. See all agents for the current repository

Or from the terminal:

git worktree list

Removing a Worktree

1. Open Settings > Agents
2. Right-click the agent
3. Select Remove Agent

Or from the terminal:

git worktree remove ../my-feature

Best Practices

Naming Conventions

Use clear, descriptive names for worktree directories:

myproject/           # Main worktree
myproject-feature/   # Feature branch
myproject-hotfix/    # Hotfix branch
myproject-review/    # For code reviews

Shared vs. Separate

Worktrees share the same Git history but have:

• Separate working directories
• Separate staged changes
• Shared commits and branches

Cleanup

Remove worktrees you're no longer using:

git worktree prune  # Clean up stale worktree references

Setup Scripts

You can configure a setup script that runs automatically when a new worktree is created. This is useful for:

• Installing dependencies (npm install, bundle install, etc.)
• Copying environment files
• Running project-specific initialization

Configuration

Create a file at .agentastic/setup.sh in your repository root:

#!/bin/bash
# .agentastic/setup.sh
set -euo pipefail

echo "Setting up worktree: $AGENTASTIC_BRANCH"

# Copy .env files using helper script (if you have one)
if [ -x "$AGENTASTIC_MAIN_REPO_PATH/scripts/copy_env_files.sh" ]; then
  "$AGENTASTIC_MAIN_REPO_PATH/scripts/copy_env_files.sh" \
    "$AGENTASTIC_MAIN_REPO_PATH" \
    "$AGENTASTIC_WORKTREE_PATH"
else
  # Fallback: copy critical .env files manually
  for env_file in ".env" ".envrc" "backend/.env" "frontend/.env"; do
    if [ -f "$AGENTASTIC_MAIN_REPO_PATH/$env_file" ]; then
      mkdir -p "$(dirname "$AGENTASTIC_WORKTREE_PATH/$env_file")"
      cp "$AGENTASTIC_MAIN_REPO_PATH/$env_file" "$AGENTASTIC_WORKTREE_PATH/$env_file"
      echo "Copied $env_file"
    fi
  done
fi

# Install dependencies (uncomment what applies to your project)
# npm install
# bundle install
# pip install -r requirements.txt

echo "Worktree setup complete for $AGENTASTIC_BRANCH"

Make the script executable:

chmod +x .agentastic/setup.sh

Helper Script for .env Files

For projects with multiple .env files, create a reusable copy script:

#!/usr/bin/env bash
# scripts/copy_env_files.sh
# Copy all .env files from source to destination preserving structure

set -euo pipefail

SOURCE_DIR=$1
DEST_DIR=$2

find "$SOURCE_DIR" -name '.env' -type f | while read -r FILE; do
  RELATIVE_PATH=${FILE#"$SOURCE_DIR"/}
  TARGET_PATH="$DEST_DIR/$RELATIVE_PATH"
  mkdir -p "$(dirname "$TARGET_PATH")"
  cp "$FILE" "$TARGET_PATH"
  echo "Copied $RELATIVE_PATH"
done

Environment Variables

The setup script receives these environment variables:

Variable	Description	Example
AGENTASTIC_BRANCH	Name of the new branch	feature-login
AGENTASTIC_BASE_BRANCH	Base branch name (empty if current HEAD)	main
AGENTASTIC_WORKTREE_PATH	Absolute path to the new worktree	/Users/dev/repo-worktrees/feature-login
AGENTASTIC_MAIN_REPO_PATH	Absolute path to the main repository	/Users/dev/repo
AGENTASTIC_COMMIT	Commit SHA of the new worktree	abc123def456...
AGENTASTIC_REPO_NAME	Repository folder name	my-project

Behavior

• The .agentastic folder is automatically created in new worktrees if it doesn't exist
• The script is executed from the new worktree's .agentastic/setup.sh
• Script execution is non-blocking - if it fails, worktree creation still succeeds
• The "Worktree Setup" task appears in your workspace tasks for manual re-runs

Example: Python Project

#!/bin/bash
python -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

Using TUI Agents with Worktrees

Git worktrees are ideal for running AI coding agents like Claude Code, Codex, or other TUI (Terminal User Interface) agents. Each agent gets an isolated environment where it can make changes without affecting your main work.

Why Worktrees for AI Agents?

• Isolation - Agent changes don't affect your main branch
• Easy Review - Compare agent's work against the base branch
• Safe Cleanup - Delete the worktree if results aren't useful
• Parallel Agents - Run multiple agents on different tasks simultaneously

Claude Code Workflow

1. Create a worktree: Cmd+Shift+T
2. Open terminal in the worktree: Cmd+T
3. Run Claude Code:

   claude
   

4. Give Claude your task and let it work
5. Review the diff when done (see Diff Viewer)
6. Create a PR or merge the changes

Codex Workflow

# In your worktree terminal
codex

# Or for a specific task
codex "implement user authentication"

Generic TUI Agent Pattern

Most TUI agents follow this pattern:

# Navigate to worktree (automatic when using Agentastic)
cd /path/to/worktree

# Run your agent
my-agent

# Review changes
git diff

# Commit and push when satisfied
git add . && git commit -m "Agent-generated changes"
git push -u origin feature-branch

Happy-Path Workflow

The recommended workflow for using Agentastic with AI agents:

1. Clone Your Repository

git clone https://github.com/you/project.git
cd project

2. Create a Worktree

Press Cmd+Shift+T or go to Settings > Agents > Create Agent.

• Enter a branch name (e.g., feature-auth)
• Select the base branch (usually main)
• Click Create

The setup script runs automatically if configured.

3. Run Your Agent

Switch to the new worktree with Cmd+Option+Down, then open a terminal:

# Claude Code
claude "Add user authentication with JWT tokens"

# Or Codex
codex "Add user authentication with JWT tokens"

4. Review the Diff

• Use the Diff Viewer to review changes
• Or run Code Review with AI agents

5. Create a Pull Request

# Push your branch
git push -u origin feature-auth

# Create PR with GitHub CLI
gh pr create --title "Add JWT authentication" --body "AI-generated implementation"

6. Clean Up

After merging, remove the worktree:

1. Switch to another agent: Cmd+Option+Up
2. Go to Settings > Agents
3. Right-click the agent and select Remove Agent

Or from terminal:

git worktree remove ../project-worktrees/feature-auth
git branch -d feature-auth  # Delete local branch

Simple Workflow Example

1. Working on a feature in the main worktree
2. Need to review a PR: Cmd+Option+Down
3. Switch to a review worktree already checked out to the PR branch
4. Review the code
5. Cmd+Option+Up to return to your feature

Troubleshooting

"Branch already checked out"

A branch can only be checked out in one worktree. Either:

• Switch to a different branch in the existing worktree
• Remove the worktree using that branch

Worktree Not Appearing

Run git worktree prune to clean up stale references, then check Settings > Agents again.