How Claude Code Completely Broke My Git Worktree | by Hideaki Takahashi | Jun, 2026 | MediumSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

How Claude Code Completely Broke My Git Worktree

Hideaki Takahashi

9 min read·<br>Just now

Listen

Share

Press enter or click to view image in full size

In today’s development environments, where AI agents are becoming increasingly common, it is becoming more important to manage parallel work by multiple agents and long-running tasks efficiently. One solution that many development teams are paying attention to is Git Worktree.<br>However, Git Worktree is only a mechanism for separating Git working directories. It is not a sandbox. As a result, an agent may accidentally interfere with another working environment, or in some cases even damage it.<br>In this article, I will introduce an incident I actually encountered, where Claude Code modified and damaged files outside the worktree it had been launched from. I will then explain how the sandbox-style Worktree feature of h5i, a next-generation Git workflow tool, can help prevent this kind of problem.<br>Repository: https://github.com/h5i-dev/h5i<br>1. What is Git Worktree?<br>Git Worktree is a Git feature that lets you create multiple working directories for a single Git repository. Normally, a Git repository has one working directory, and you switch branches inside it as you work. However, each time you switch branches, you may need to stash ongoing changes, and build artifacts may be replaced. This can be inconvenient when you want to work on multiple tasks at the same time.<br>With Git Worktree, you can check out different branches of the same repository into separate directories at the same time. For example, you can continue normal development in your main working directory, open a bug-fix branch in another worktree, and let an AI agent make experimental changes in yet another worktree.<br>git worktree add ../project-agent-a feature/agent-a<br>git worktree add ../project-agent-b feature/agent-bThis creates separate directories named ../project-agent-a and ../project-agent-b, each working on a different branch. Since both are still tied to the same Git repository, you can use normal Git operations such as committing, merging, and checking diffs.<br>This makes Git Worktree a good fit for parallel development with AI agents. If you assign a separate worktree to each agent, each agent can work independently on its own branch. A human developer can later inspect the diffs from each worktree and merge only the changes they actually want.<br>However, the important point is that Git Worktree only separates Git working directories. It does not isolate processes or the filesystem. Each worktree exists as a separate directory, but that does not mean it cannot access its parent directory or neighboring worktrees. In other words, an agent may still accidentally modify files under ../project-agent-b or in the user’s home directory.<br>2. Incident: Claude Code Modified Files Outside a Git Worktree<br>The actual incident was a little more complicated, but in this article I will use a simplified example to make the core issue easier to understand.<br>The key point is that Git Worktree separates working directories, but it does not isolate the filesystem. Even if an AI agent is launched inside one worktree, it can still access the parent directory, neighboring worktrees, and the original checkout, just like any normal process.<br>In the example below, Claude Code is supposed to work inside a worktree called plain-agent. However, because of a relative path inside a build script, it ends up modifying a file in repo, the main checkout.<br>2.1. Setting up the environment<br>First, we register the directory names used in this experiment as environment variables and initialize the test environment.<br>export ROOT=$HOME/h5i-worktree-experiment<br>export PARENT=$ROOT/repo<br>export PLAIN=$ROOT/plain-agent<br>rm -rf "$ROOT"; mkdir -p "$PARENT"Here, $PARENT is the directory where the main checkout will be placed. We then initialize a Git repository and create a small static-site-like project.<br>cd "$PARENT"<br>git init -q -b main

mkdir -p src published

printf '# Welcome\n\nHello from the site.\n' > src/index.md<br>printf 'MY REAL HOMEPAGEhand-written, v0.0.1\n' \<br>> published/index.htmlThink of published/index.html as a generated file equivalent to production output. In a real project, this might correspond to a documentation site, a demo page, generated assets, or local artifacts that you manage manually.<br>Next, we prepare a build script.<br>cat > build.sh WelcomeHello from the site." > ../repo/published/index.html<br>echo "published -> ../repo/published/index.html"<br>EOF

chmod +x build.shAt first glance, this looks like a simple build script. The important detail is that the output destination is ../repo/published.<br>A human developer might notice before running it that this script writes outside the current worktree. However, if you simply ask an AI agent to “build and preview...