Git worktrees explained: a beginner's guide for AI coding

Short answer: a git worktree is an extra working folder linked to the same repository, with a different branch checked out. You can have main open in one folder and a feature branch in another, at the same time, without cloning twice or stashing. That is exactly what AI coding agents need: one folder per task, so parallel agents never overwrite each other's files.

Worktrees have been part of git since 2015, yet many developers have never used them. AI coding agents made them suddenly useful for everyone.

Disclosure: we build Zokie, an agent IDE that creates a worktree for every task. This guide works with plain git.

Branch vs clone vs worktree

The five commands you need

# Create a new branch in a new folder next to your repo
git worktree add ../myapp-login-fix -b login-fix

# See every worktree
git worktree list

# Work in it like any folder
cd ../myapp-login-fix && npm install && npm test

# Remove it when the branch is merged
git worktree remove ../myapp-login-fix

# Clean up records of folders you deleted by hand
git worktree prune

Rules worth knowing

• One branch per worktree. Git will not let two worktrees check out the same branch.
• Each worktree needs its own install. node_modules, virtual environments and build folders are per folder.
• Ignored files do not come along. Copy .env files you need, or better, load secrets from a manager.
• Remove, do not just delete. Use git worktree remove so git forgets the folder.

Why AI agents love worktrees

When two agents work in the same folder, one agent's edits land in the middle of the other's work, tests fail for reasons neither caused, and the diff mixes two tasks. With a worktree per task:

• Each agent sees only its own changes.
• Each task's diff is clean and reviewable on its own.
• A bad run is thrown away by deleting one folder and one branch.
• Your own main folder stays untouched while agents work.

Our step-by-step guide to running several AI coding agents at once shows the full workflow by hand.

Worktrees without the commands

Zokie creates a worktree and branch for every task automatically, runs the agent there (Claude Code, Codex, Gemini CLI or Cursor CLI), shows you the diff against main and turns it into a pull request when you approve. Free to start, invite only for now: get an invite.

FAQ

What is the difference between a git branch and a worktree?

A branch is a line of commits. A worktree is a folder where a branch is checked out. Worktrees let you have several branches checked out at once, each in its own folder.

Do git worktrees use a lot of disk space?

Less than a second clone, because they share the repository's history and objects. Each worktree only adds its checked-out files and its own build and dependency folders.

Can two worktrees use the same branch?

No. Git allows each branch to be checked out in only one worktree at a time.

Why do AI coding tools use git worktrees?

So several agents can work on the same repository at once without editing the same files, and so each task ends as its own clean diff.