DocsDocumentation

Git Worktrees

Working with multiple branches simultaneously using 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#

Open Settings (Cmd+,)
Go to Agents
Click Create Agent
Choose a branch and destination folder

From Command Line#

You can also create worktrees via the integrated terminal:

bash

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

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

From an Open Pull Request#

When picking a base branch — in Agent Home or the New Worktree dialog — the branch picker also lists your repository's open pull requests alongside branches, searchable by title, author, or branch name. Draft PRs are labeled, and each row shows the author and source branch. Pick one and the new worktree is checked out directly to that PR's branch, ready to review or continue the work.

This needs a connected GitHub account for private or organization repositories — add or re-authenticate one under Settings > Accounts if pull requests aren't showing up.

Switching Worktrees#

Using Keyboard Shortcuts#

Action	Shortcut
Switch Worktree	`Ctrl`+`Tab`
Next Agent	`Cmd`+`Option`+`Down`
Previous Agent	`Cmd`+`Option`+`Up`

The Worktree Switcher Panel#

Pressing Ctrl+Tab opens a switcher panel, much like macOS's App Switcher: hold Ctrl and tap Tab to cycle through worktrees, then release to switch to the highlighted one. You can also type to search by name, or navigate with the arrow keys.

Each row shows what's going on in that worktree — notified, waiting for you, agent active, recently visited, or not visited recently — plus a badge for remote worktrees and a marker on the one you're currently in. The footer reminds you of the controls: ↑↓ Navigate ⌃⇥ Cycle ↩ Switch esc Cancel.

Switcher Order#

Control how worktrees are ordered in the switcher panel from Settings > Worktrees > Worktree Switcher Order:

Option	Order
Visited + Notified (default)	Blends recent visits and notifications
Recently Visited	Most recently opened first
Recently Notified	Worktrees needing your attention first

From Settings#

Open Settings > Agents
Click on an agent to switch to it

From Command Palette#

Open Command Palette (Cmd+Shift+P)
Type "worktree"
Select Switch to Worktree
Choose the target worktree

Managing Worktrees#

Viewing All Worktrees#

Open Settings > Agents
See all agents for the current repository

Or from the terminal:

bash

git worktree list

Removing a Worktree#

Open Settings > Agents
Right-click the agent
Select Remove Agent

Or from the terminal:

bash

git worktree remove ../my-feature

Best Practices#

Naming Conventions#

Use clear, descriptive names for worktree directories:

code

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:

bash

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:

bash

#!/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:

bash

chmod +x .agentastic/setup.sh

Helper Script for .env Files#

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

bash

#!/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#

bash

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

Containers#

For even greater isolation, you can run agents inside Docker containers. Each container-backed worktree gets:

Isolated filesystem and network
Pre-installed tools (Claude Code, Codex, etc.)
Reproducible environments

See Docker Containers for full documentation.

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#

Create a worktree: Cmd+Shift+T
Open terminal in the worktree: Cmd+T
Run Claude Code:
bash
claude
Give Claude your task and let it work
Review the diff when done (see Diff Viewer)
Create a PR or merge the changes

Codex Workflow#

bash

# In your worktree terminal
codex

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

Generic TUI Agent Pattern#

Most TUI agents follow this pattern:

bash

# 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#

bash

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:

bash

# 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#

bash

# 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:

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

Or from terminal:

bash

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

Simple Workflow Example#

Working on a feature in the main worktree
Need to review a PR: Cmd+Option+Down
Switch to a review worktree already checked out to the PR branch
Review the code
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.