What does a git worktree not isolate for AI coding agents?

A git worktree isolates files and the branch, not behavior. Three things stay shared with your main checkout: the repository's .git directory, project-scope plugins, and saved permission approvals. That is why two AI coding agents working in separate worktrees can still reach each other, and why the useful question is not whether worktrees isolate, but what exactly you are trying to protect: your files, or your machine.

This became a public argument on July 30, 2026, when a Hacker News thread titled "Git worktrees are not an isolation boundary for coding agents" collected 35 comments. The substantive ones split between people who run agents in worktrees daily and people who think the framing is a straw man.

What does a git worktree actually isolate for an AI coding agent?

A git worktree gives an AI coding agent its own working directory and its own branch, checked out from the same repository. Edits made by an agent in ../project-feature-a do not appear in your main checkout, and the two branches advance independently until someone merges them. For the failure mode most people are trying to avoid, which is two agents writing the same file minutes apart and the second silently winning, a worktree solves it completely.

That is the boundary being bought, and it is a real one. On Hacker News, the user markush_ put the positive case in one line: "The big advantage of using worktrees is the shared git state, it makes it so much easier to cherry-pick and move commits around those worktrees." The shared repository is not an oversight in the design. It is the feature, and it is what makes a worktree cheaper and faster than a second clone. We covered the mechanics of creating one, and the dependencies and build artifacts that do not come along, in our guide to git worktrees for AI coding agents. This article picks up where that one stops: after the worktrees exist and the agents still collide.

What stays shared between a worktree and the main checkout?

Anthropic's Claude Code documentation answers this directly in a section called "What worktrees share with the main checkout", read on August 12, 2026. It names three items, and each has a different consequence for someone running parallel AI coding agents.

• The repository's .git directory. Per the documentation, git commands run inside a worktree write to the main repository's shared .git directory, and it adds that sandboxing allows those writes, so commands such as git commit work from inside a worktree with the sandbox enabled.
• Project-scope plugins. Plugins installed at project scope from the main checkout also load in worktrees of the same repository, so they do not need reinstalling per worktree. The documentation ties this behavior to Claude Code v2.1.200 or later.
• Saved permission approvals. Choosing "Yes, don't ask again" for a Bash command inside a worktree session saves the rule to the main checkout's .claude/settings.local.json, so it applies in the main checkout and in every other worktree of that repository, and it survives the worktree being deleted. The documentation notes this changed in v2.1.211: before that version, the approval was saved inside the worktree and was lost with it.

The third item is the one worth rereading. A permission you grant to one agent, in a throwaway directory, to get past one annoying prompt, becomes a standing permission for every agent you run in that repository afterwards.

Can an AI coding agent in a worktree change your main checkout?

Through plain git, yes, and you can prove it to yourself in about thirty seconds. Because .git is shared, a process running inside a worktree can write to .git/hooks, and hooks placed there run when you commit from the main checkout. This block works in a temporary directory, does the demonstration, and removes everything it made:

d=$(mktemp -d) && cd "$d"
git init -q demo && cd demo
git -c user.email=a@b.c -c user.name=t commit -q --allow-empty -m first
git worktree add -q ../agent-a -b agent-a
cd ../agent-a
printf '#!/bin/sh\necho "hook written from the worktree"\n' > "$(git rev-parse --git-common-dir)/hooks/pre-commit"
chmod +x "$(git rev-parse --git-common-dir)/hooks/pre-commit"
cd ../demo
git -c user.email=a@b.c -c user.name=t commit -q --allow-empty -m second
cd "${d:?}"; git -C demo worktree remove --force ../agent-a; rm -rf "${d:?}/demo" "${d:?}/agent-a"

On a default git configuration, with no core.hooksPath override, the second commit prints hook written from the worktree. We ran this on git 2.50.1 on August 12, 2026. If your machine sets core.hooksPath, which husky, lefthook and many corporate configurations do, git looks for hooks elsewhere and the command prints nothing: the demonstration goes silent rather than wrong. The ${d:?} on the last line is not decoration. It makes the shell abort instead of expanding to an empty string if mktemp ever fails, which is the difference between deleting a temporary directory and deleting a path at the root.

What the result means, stated carefully. No file tracked by git changed and no branch was touched, so git status in the main checkout stays clean. The write landed inside the main checkout's .git directory, which physically lives inside the main checkout folder. That is the whole point: the change is invisible to the command people use to look for changes, and a script that only ever existed inside the isolated directory now runs on your machine, triggered by your own commit. The command git rev-parse --git-common-dir is the trick, because from inside a worktree it prints the path of the main repository's .git, which is the shared surface.

The Hacker News thread did not leave this open for long, and the exchange is worth reporting in full because it narrows what the demonstration proves. The user alchaplinsky asked whether an agent confined to a sandbox profile "can still write a pre-commit hook that runs on your machine whenever you commit outside the sandbox", and ended with "Or am I missing something?". The user sbysb, who had recommended that sandboxing tool and runs it with a profile of their own team's making, answered that "All git config and hooks are not writable inside the sandbox". So inside the profile that team runs, the answer is no. The same commenter then drew the sharpest distinction in the whole thread, and it cuts against their own setup: "this doesn't close all of these types of attacks, just the ones that are invisible". An agent can still write a script and wire it into your code, but that arrives as a change you can read in a diff. A git hook does not. What the block above adds is the baseline underneath all of it: on plain git, with no sandbox and no harness enforcing anything, the mechanism works exactly as alchaplinsky described it. This is not a vulnerability in git and not a bug in any agent. It is the shared repository doing what it is designed to do, and what it establishes is narrow and useful: file isolation and process isolation are different properties, and a worktree only sells the first.

What does Claude Code block inside a worktree, then?

The shared .git directory is exactly the gap the harness layer exists to close, and Claude Code publishes what it enforces. In a section titled "How Claude Code enforces isolation", read on August 12, 2026, the documentation lists four checks applied while a session is isolated in a worktree, covering the session and every subagent it spawns.

Claude Code blocks an Edit, Write or NotebookEdit that targets a path in the main checkout. It blocks a Bash, PowerShell or Monitor command whose working directory resolves to the main checkout. It blocks commands that redirect git into the main checkout, whether through git -C, --git-dir, the GIT_DIR and GIT_WORK_TREE variables, or a cd before running git. And it blocks commands whose shape it cannot statically verify as staying inside the worktree, such as brace expansion and heredocs with unquoted delimiters, a check the documentation says cannot be turned off.

The practical reading for anyone running parallel agents: your isolation guarantee comes from the harness, meaning the layer that runs the agent, whether that is Claude Code, Codex or a runner you wrote yourself. It does not come from git. If you swap the harness or launch an agent through a wrapper that skips those checks, the boundary you thought you had goes with it.

Does a git worktree isolate the database, the dev server or the ports?

No, and this is the collision that surprises people who did everything right. A worktree copies tracked files. It does not give an AI coding agent its own PostgreSQL database, its own Redis, its own port 3000, or its own Docker stack. Five agents in five worktrees share one development database, and a destructive migration run by any of them lands on all five.

The Hacker News thread is full of people who hit this and built around it. One commenter, francislavoie, described a Claude hook that runs a custom worktree creation script, copying node_modules and the .env into the new worktree "plus doing some edits to the .env to isolate it so it can run in parallel", and giving each worktree its own Docker Compose project name. Another, madarco, said of a dedicated sandboxing tool that a commenter had just recommended: "nono is great but you'll still won't be able to run multiple dev servers, dbs or test in the browser". The commenter who recommended that tool, sbysb, disputed it in the next comment, answering that "With our profile setup you can do all three of those things". We are not refereeing that disagreement, because the point about worktrees does not depend on it, and the point is ours rather than either of theirs: nothing in git worktree add allocates a port, a database or a browser profile.

The cheap mitigations, in the order we would try them: give each worktree its own port through an edited .env, give each one its own Docker Compose project name, and make the test suite use an in-memory or per-worktree database rather than the shared development one. None of those come from git worktree add. They are setup you write once and reuse.

How do you copy .env and node_modules into a new worktree?

A worktree is a fresh checkout, so gitignored files such as .env and .env.local are simply not there, which in our experience is the first thing that breaks in a newly created worktree. Claude Code documents a mechanism for this: a .worktreeinclude file in the project root, using gitignore syntax, listing the files to copy into each new worktree. Per the documentation read on August 12, 2026, only files that both match a pattern and are gitignored get copied, so tracked files are never duplicated, and this applies to worktrees created with --worktree, to subagent worktrees, and to parallel sessions in the desktop app.

One caveat the page states, and one we add ourselves. The page says that if you replace worktree creation with a WorktreeCreate hook, the copying has to happen inside your hook script. Ours, which the page does not make: its own example lists config/secrets.json, and a .worktreeinclude that lists a secrets file is a decision about blast radius, because it puts a copy of that file in every directory an agent works in.

Worktree, clone or container: which one does your setup need?

The three options answer three different questions, and the Hacker News thread argued all of them. The user firasd framed the choice by what you are preserving: "[t]he answer is: non-pushed changes", which is what both worktrees and clones protect. A separate clone gives you a .git of its own, so the shared-hooks surface above disappears, and it is cheaper than it sounds: as the user alchaplinsky noted in the same thread, git clone --shared writes an alternates file pointing at your object store and copies zero objects. We confirmed that behavior on August 12, 2026.

For process and network isolation, neither is the answer. The user QuercusMax said it in two sentences: "If you want to properly isolate things, use containers. That's not what worktrees are for." That is the honest ceiling. A container or a virtual machine is what you want before leaving an AI coding agent running unsupervised, because it is the only option in this list that isolates what the agent can execute rather than what it can edit.

A rough decision rule: worktrees for parallel supervised work on a machine you trust, clones when you want a separate .git and independent hooks, containers when the agent runs without someone watching.

What this article does not prove

The hook demonstration establishes that a shared .git is reachable from a worktree, on git 2.50.1, on August 12, 2026, with no core.hooksPath override and no sandbox in the way. It says nothing about whether a given sandboxing tool blocks the same write, and one commenter in the thread says the profile their team runs does block it. It also does not measure how often this causes real damage, and we have no data saying it commonly does. Every comment quoted here is a named individual's experience, not a survey, and the thread contains people arguing the opposite position with equal conviction, including one who said worktrees work as intended for most people.

Disclosure about a source. The user alchaplinsky, quoted twice here, is Alex Chaplinsky, who wrote the linked post and submitted it to Hacker News. One commenter there accused Chaplinsky of arguing a straw man to sell a product. Chaplinsky did not answer that in the thread, and we did not test the accusation. We did check the two technical claims by Chaplinsky that appear in this article, and both hold.

The Claude Code behaviors described come from the vendor's own documentation, read on August 12, 2026, and not from our testing of each check. Documentation can lag the product in both directions. Finally, this article is about isolation boundaries only. Whether running many agents in parallel is a good idea at all is a separate question, and one we answered less confidently in how many AI agents you can actually run in parallel.