When you ask Claude Code, Cursor, Codex, or a similar tool to edit code, an awkward problem appears quickly. The AI changes files in your current working directory, and when it finishes, its work is mixed with your own uncommitted changes. You cannot tell at a glance who wrote which line. Run two unrelated AI tasks at once and they can overwrite each other's files. Rolling back is worse because you may not know every file the Agent touched.
Git Worktree provides a clean solution: one repository with multiple independent working directories. Give every AI task its own worktree and its changes are isolated by default, the diff is unambiguous, the entire attempt can be discarded at any time, and multiple tasks can run in parallel without interference. This guide explains the complete workflow.
The central idea of Worktree: one .git repository exposes multiple independent working directories, each checked out on its own branch.
What Is Git Worktree?
A conventional Git repository has one working directory. Switching branches replaces the contents of that directory, which is why Git blocks a switch when uncommitted changes would be overwritten. git worktree removes that limitation. It lets one repository be checked out into several directories at the same time, with each directory on a different branch and all of them sharing the underlying .git object database. There is no duplicate history on disk and no need to clone again.
# 在主仓库旁边，为一个新分支创建独立工作目录
git worktree add ../myproject-ai-task-1 -b ai/refactor-auth
# 现在有两个目录：
# myproject/ ← 你自己在 main 上工作
# myproject-ai-task-1/ ← AI 在 ai/refactor-auth 分支上工作
# 两者共享同一个仓库历史，互不干扰This capability is almost purpose-built for AI-assisted programming because it separates the AI's changes from yours at the filesystem level.
Why AI-Assisted Development Benefits So Much
| Problem | Editing the Main Workspace Directly | Using a Worktree |
|---|---|---|
| Ownership of changes | AI edits are mixed with your uncommitted work | Every AI change lives in a separate directory and branch |
| Review diff | You must separate your edits from the AI's manually | git diff main shows the AI's complete change set |
| Rollback | Confirm each file individually and risk missing one | Remove the entire worktree with no residue |
| Parallel tasks | Two tasks can overwrite one another | Give each task a worktree and run them together |
| Your regular work | The main directory becomes unavailable while AI runs | Keep using the main directory while AI works elsewhere |
The ability to see everything the AI changed at a glance directly affects both review speed and confidence. It is also a key part of reducing the risk that AI breaks a project.
Complete Workflow
1. Create a Worktree for Every Task
Choose a shared location, such as ../worktrees/ beside the project, and use an ai/ branch prefix for easy identification:
git worktree add ../worktrees/fix-login -b ai/fix-login
cd ../worktrees/fix-login
# 在这里启动 AI 工具，让它只在这个目录里工作2. Let the AI Work in the Isolated Directory
Start Claude Code, Cursor, or Codex from the worktree directory. Every read and write happens there. Your main workspace remains untouched, so you can continue your own development or open another worktree for a second task.
3. Review Every Change with One Command
When the task is complete, the AI's work is exactly the difference between its branch and the main branch:
git diff main...ai/fix-login # 看全部改动
git diff main...ai/fix-login --stat # 先看改了哪些文件、各多少行None of your own edits are mixed into the result, which makes review clean and direct. If the changes are acceptable, choose how to merge them.
4. Merge or Discard
# 满意 → 合并回主分支
cd ../../myproject
git merge ai/fix-login
# 不满意 → 整个丢弃，干干净净
git worktree remove ../worktrees/fix-login
git branch -D ai/fix-loginDiscarding is one of the best parts of this workflow. If the AI ruins the task, remove the worktree and branch and the repository returns to the state in which nothing happened. There is no need to restore files one by one with git checkout.
Reviewing an AI task becomes `git diff main...branch`: the worktree establishes the change boundary automatically.
Running Multiple AI Tasks in Parallel
Parallel work is where Worktree becomes especially powerful. Create three worktrees for three unrelated tasks, then assign one AI session to each:
git worktree add ../worktrees/task-a -b ai/task-a
git worktree add ../worktrees/task-b -b ai/task-b
git worktree add ../worktrees/task-c -b ai/task-c
# 三个终端 / 三个 AI 会话并行，互不干扰
git worktree list # 随时查看所有工作目录及其分支Review each task separately when it finishes, then merge or discard it. This model—one developer supervising a small team of AI sessions—is one of the clearest productivity gains in AI-assisted development today. Tools such as Claude Code are adding native support for creating a worktree per task, but understanding the underlying git worktree command keeps the workflow portable across tools.
A small script can reduce worktree creation to one command:
# ai-task.sh：ai-task.sh fix-login → 建好并进入
name="$1"
git worktree add "../worktrees/$name" -b "ai/$name" && cd "../worktrees/$name"Important Considerations and Common Pitfalls
- Install dependencies in each worktree: The directories share Git history, but ignored directories such as
node_modulesand.venvare not shared. Runnpm installin a new worktree. Large projects can speed this up with pnpm or carefully managed dependency symlinks. - One branch cannot be checked out by two worktrees at once: Git blocks this as a safety mechanism. Use a distinct branch for every worktree.
- Local environment files: Files such as
.envand other ignored local configuration do not appear automatically. Copy or symlink them as appropriate. - Clean up with Git commands: Do not delete a worktree directory directly with
rm -rf, which leaves stale registration in Git. Usegit worktree remove; if the directory was deleted another way,git worktree pruneremoves stale metadata. - Disk and ports: When running several tasks in parallel, watch for local port collisions. Each worktree needs a different port if it runs its own development server.
Dependency installation and port allocation are the two most common obstacles in a parallel worktree workflow.
Who This Is For and Alternatives
This workflow is for developers who use AI tools to modify code and care about controlled changes and efficient review, especially those running multiple AI tasks in parallel. There are two main alternatives:
- Traditional branches plus stash: Stay in one directory and use
git stashand branch switching for isolation. This works for occasional use, but repeated switching becomes confusing and does not support true parallel execution. - Container or cloud isolation: Run the AI in a Docker container or cloud sandbox, as some Agent platforms do. Isolation is stronger and safer, but environment setup is heavier. For individual local development, Worktree offers the best balance of simplicity and value.
Frequently Asked Questions
Q: Does Worktree make a repository much larger? A: No. Every worktree shares the same .git object database and adds only its own working files. Separate dependency directories such as node_modules, not Git data, consume most of the extra space.
Q: Can AI tools use a worktree automatically? A: A growing number of tools provide native support by creating an isolated workspace for each task. Even when a tool does this, understanding git worktree gives you manual control, works across tools, and makes automation scripts easy to write.
Q: How is this different from making several clones? A: Each clone has a separate repository and history. Branches and commits must be synchronized through push and pull, and history consumes disk space repeatedly. Worktrees share one repository, so branches and commits are available immediately with less overhead.
Summary
Git Worktree separates the AI's changes from your own work at the filesystem level. Each task receives one directory and one branch; review is a single git diff, rollback means removing one worktree, and several tasks can run in parallel. The workflow has almost no learning curve but substantially increases your control over AI code changes. After all, the prerequisite for letting AI edit freely is knowing that you can see every change and restore the original state at any time.