Skip to content
Agentic Coding Toolkit
This feature requires ACT Pro. Compare plans →

Git Worktrees

Work on multiple features in parallel without stashing, branch-switching, or losing context. The /git-worktree skill manages isolated directories that share a single git history.

Scenario

Section titled “Scenario”

You are midway through a feature branch when a critical bug report comes in. Instead of stashing your work and switching branches, you create a separate worktree for the bugfix and work on both in parallel, each in its own directory with its own Claude session.

Prerequisites

Section titled “Prerequisites”
  • ACT Pro installed and verified (/act:help)
  • A git repository (the project must be tracked by git)
  • Familiarity with basic git branch operations

How worktrees help

Section titled “How worktrees help”

A git worktree is a separate checkout of the same repository. Each worktree has its own working directory and branch, but they all share the same .git history. This means:

  • No stashing or losing uncommitted work
  • Instant context switching (just open a different terminal)
  • Independent flutter pub get, build caches, and IDE windows per worktree
  • .env files are automatically copied to new worktrees

Steps

Section titled “Steps”

1. Create a worktree for the bugfix

Section titled “1. Create a worktree for the bugfix”

From your main project directory, run:

Terminal window
/git-worktree create fix-login-crash

This creates a new directory (sibling to your project) with a fresh checkout on a new fix-login-crash branch. Your .env files are automatically copied over.

2. List active worktrees

Section titled “2. List active worktrees”

Check what worktrees are currently active:

Terminal window
/git-worktree list

You will see your original working directory and the new bugfix worktree, each on its own branch.

3. Work in the bugfix worktree

Section titled “3. Work in the bugfix worktree”

Open a new terminal, navigate to the bugfix worktree directory, and start a Claude session there:

Terminal window
cd ../my-project--fix-login-crash
claude

Work on the bugfix independently. Your original feature branch remains untouched in the original directory.

4. Switch context between worktrees

Section titled “4. Switch context between worktrees”

To switch which worktree you are focused on:

Terminal window
/git-worktree switch fix-login-crash

This helps the AI understand which worktree context you want to work in.

5. Copy environment files to an existing worktree

Section titled “5. Copy environment files to an existing worktree”

If you update your .env after creating a worktree:

Terminal window
/git-worktree copy-env fix-login-crash

This copies the latest .env files from the main worktree to the target.

6. Clean up when done

Section titled “6. Clean up when done”

After the bugfix is merged, remove the worktree:

Terminal window
/git-worktree delete fix-login-crash

This removes the worktree directory and cleans up git’s internal tracking. To remove all worktrees except the main one:

Terminal window
/git-worktree cleanup

Expected output

Section titled “Expected output”
  • A new sibling directory named <project>--<branch-name> for each worktree
  • Each worktree on its own branch with independent working state
  • .env files copied automatically on creation
  • git log showing the same shared history across all worktrees
  • Clean removal when worktrees are deleted

Common pitfalls

Section titled “Common pitfalls”
  • Checking out the same branch in two worktrees — Git does not allow this. Each worktree must be on a different branch. If you need the same code, create a new branch from it.
  • Forgetting to install dependencies — Each worktree has its own dart_tool directory. Run flutter pub get in new worktrees before building.
  • Leaving stale worktrees — Old worktrees consume disk space and can cause confusion. Use /git-worktree cleanup periodically to remove worktrees whose branches have been merged.
  • Editing the same file in two worktrees — Git handles this correctly at the branch level, but be aware that both directories are independent. Changes in one do not appear in the other until committed and merged.

Next steps

Section titled “Next steps”