Why AI Should Never Write Directly to Main: A Worktree Isolation Workflow

You may have experienced AI agents simultaneously fixing login bugs, refactoring pages, and adding tests, all writing to the same checkout. After a short time the workspace becomes a tangled mix of changes, making it impossible to tell which modification belongs to which task.

When multiple agents start writing files, where should they write?

The usual answer is not “the same checkout.” A better default is to give each independent task its own worktree .

Worktree is not a branch but a second workspace

Many people hear “Git worktree” and assume it is merely an advanced branch technique, which underestimates its power. The Git documentation defines a worktree as a repository that can have multiple working trees, each checking out a different branch ( git worktree add creates a new directory that shares history but has its own HEAD and index).

Branch is a task line; worktree is the independent workspace for that line.

Using only branches means you keep switching on the same desk; a slip, a missed stash, or an agent looking at the wrong path quickly creates chaos. With worktrees, each task gets its own desk:

git worktree add ../repo-login-fix -b fix/login main
git worktree add ../repo-settings-refactor -b refactor/settings main
git worktree list

The login fix lives in ../repo-login-fix, the settings refactor in ../repo-settings-refactor. The directories are completely independent, so you can run tests in one while another agent continues coding in the other.

Why worktrees matter for AI coding

AI agents now spend long periods in a workspace performing exploration, modification, testing, and fixing. When several agents share the same workspace, they can overwrite each other’s files, making it hard to trace origins of changes.

Avoid real‑time overwrites.

Preserve task context – the directory name itself acts as a task label.

Make failures disposable – delete a failed worktree instead of manually undoing a dirty tree.

Note: worktrees isolate code, not the full runtime environment. They do not automatically provide separate .env files, ports, databases, Docker volumes, etc.

Four‑layer worktree process

Git isolation : use git worktree add and independent branches to prevent file and branch overlap.

Environment completion : add missing .env, .env.local, install dependencies, run setup scripts, or use .worktreeinclude to copy ignored config files.

Runtime isolation : offset ports, use separate DB schemas, name Docker volumes uniquely to avoid resource contention.

Integration gate : before merging, review diffs, run tests, and collect deterministic evidence (status, diff, test exit code).

Minimal usable workflow

Step 1 – Keep the main checkout for front‑end decisions : read requirements, design splits, view final diffs, run key validations, then merge or reject.

Step 2 – One worktree per task : name directories clearly, e.g.

git worktree add ../myapp-fix-login -b fix/login main
git worktree add ../myapp-refactor-settings -b refactor/settings main
git worktree add ../myapp-alt-checkout -b spike/checkout-copy main

Step 3 – Give each agent a task card (explicit scope, environment, acceptance criteria). Example:

you are in worktree: ../myapp-fix-login
Task: fix intermittent session‑refresh failure after login.
Scope:
- modify only auth/session, api/login and related tests.
- do NOT touch settings, billing, or DB schema.
Env:
- PORT=3101
- test DB schema: test_login_fix
Acceptance:
- run npm test -- auth
- output changed files, root cause, verification command, residual risk
- do NOT merge back to main automatically

Step 4 – Verify before merging : check the worktree, commit hash, command used, and exit code. Record evidence with:

git status
git diff --stat main...HEAD
npm test -- auth

Three common patterns

Pattern 1 – Background fix : open a worktree for a small, isolated bug while continuing main development.

Pattern 2 – Solution comparison : create three throwaway worktrees, each implementing a minimal prototype of a different approach, then compare diffs, complexity, test results, and risk, keeping only the best.

Pattern 3 – Read‑only review : open a new worktree (or a copy) for a review agent that only reads, answering questions about regressions, test gaps, out‑of‑scope diffs, and files needing manual inspection.

Cleaning up and naming

Worktrees accumulate. Use the following habit:

git worktree list
git worktree remove ../myapp-spike-cache-b
git worktree prune

Handle tasks on the day they finish: merge, keep, or delete.

Give directory names intent, e.g., fix/login-refresh instead of generic agent-a.

Do not keep a worktree as a long‑term main directory; promote stable work to a proper branch or separate project.

OpenAI Codex notes that worktrees are lightweight and disposable; permanent worktrees should be used only for long‑lived environments.

Final takeaway

AI coding can tempt you to launch many agents in parallel, but the real value lies in making each result reviewable, comparable, deletable, and mergeable. Worktrees provide the disciplined isolation needed to turn AI‑assisted coding from a toy into a productive engineering practice.

Give every file‑writing AI its own worktree.