# How Worktree Isolation Prevents Parallel Agent Conflicts in pi-subagents > Discover how pi-subagents uses worktree isolation to prevent parallel agent conflicts. Avoid corrupted state and race conditions with isolated Git worktrees for each agent. - Repository: [Nico Bailon/pi-subagents](https://github.com/nicobailon/pi-subagents) - Tags: internals - Published: 2026-06-01 --- **pi-subagents assigns each autonomous agent its own isolated Git worktree, ensuring concurrent repository operations never corrupt shared state or trigger race conditions.** The pi-subagents framework orchestrates multiple autonomous agents that frequently need to checkout, build, and commit changes to the same Git repository simultaneously. Without proper safeguards, these parallel operations would overwrite files and corrupt the shared Git index. By leveraging **worktree isolation**, the system confines each agent to a private workspace within the same repository, eliminating cross-agent interference while maintaining high performance. ## The Challenge of Concurrent Repository Access When multiple agents operate directly in a single working tree, they create dangerous race conditions. If two agents execute `git checkout` simultaneously, or if one agent modifies files while another stages changes, they overwrite each other's work and potentially corrupt the repository index. Traditional approaches like repository cloning waste disk space and network bandwidth, while file locks eliminate the parallelism essential for efficient multi-agent execution. ## How Worktree Isolation Works The implementation in [`pi_subagents/worktree.py`](https://github.com/nicobailon/pi-subagents/blob/main/pi_subagents/worktree.py) wraps Git's native worktree functionality to create lightweight, isolated environments for each agent. This architecture delivers three critical safety guarantees: ### Separate Checkout Directories When an agent starts, the manager invokes `git worktree add` to create a unique temporary directory associated with a fresh branch (e.g., `agent-`). This gives each agent a distinct physical workspace where file modifications cannot affect other agents' working files. ### Independent Index and HEAD References Each worktree maintains its own `.git` directory storing an independent index and HEAD reference. When an agent stages files with `git add` or creates commits, those operations update only that worktree's index, leaving the main repository and other agents' worktrees completely unaffected. ### Automatic Cleanup The `Worktree` class implements Python context manager protocols to ensure deterministic cleanup. Upon agent completion—or if an exception occurs—the system executes `git worktree remove` and deletes the temporary branch, guaranteeing no stray state remains to interfere with subsequent operations. ## Implementation in pi-subagents In [`pi_subagents/agent.py`](https://github.com/nicobailon/pi-subagents/blob/main/pi_subagents/agent.py), the high-level agent class utilizes the `Worktree` API to perform repository operations safely. The following pattern demonstrates how an agent obtains its isolated environment: ```python from pi_subagents.worktree import Worktree # When an agent is instantiated with Worktree(repo_path="/home/user/project") as wt: # `wt.path` points to the unique temporary directory # All Git operations below are confined to this work-tree wt.run_git("checkout -b agent-12345") wt.run_git("pull origin main") # … agent does its work (e.g., modify files, run tests, commit) wt.run_git("add .") wt.run_git('commit -m "Agent 12345 automated change"') wt.run_git("push origin HEAD") # Exiting the context automatically removes the work-tree ``` ## Parallel Execution Without Conflicts Because each thread operates on distinct worktree directories (typically located at `/tmp/pi-subagents/worktree-`), multiple agents can safely execute `git pull`, `git add`, and `git commit` simultaneously. The [`tests/test_worktree_isolation.py`](https://github.com/nicobailon/pi-subagents/blob/main/tests/test_worktree_isolation.py) file contains unit tests confirming that concurrent agents maintain independent Git states without collisions. ```python import threading from pi_subagents.agent import Agent def run_agent(name): Agent(name).execute() # internally uses Worktree as shown above threads = [ threading.Thread(target=run_agent, args=("agent-A",)), threading.Thread(target=run_agent, args=("agent-B",)), ] for t in threads: t.start() for t in threads: t.join() ``` Even though both threads execute Git commands at the same time, each operates on its own worktree directory, so their indices and HEADs never collide. ## Summary - **Isolated directories**: `git worktree add` creates unique physical workspaces for each agent (e.g., `agent-` branches) - **Independent Git state**: Each worktree maintains separate index and HEAD references, preventing cross-agent corruption - **Automatic resource management**: Context managers ensure worktrees and temporary branches are cleaned up after use via `git worktree remove` - **Parallel safety**: Multiple agents can checkout, edit, and commit concurrently without interference, as implemented in [`pi_subagents/worktree.py`](https://github.com/nicobailon/pi-subagents/blob/main/pi_subagents/worktree.py) ## Frequently Asked Questions ### What happens if two agents push to the same remote branch simultaneously? Since each agent operates on a unique temporary branch (e.g., `agent-`), they push to distinct refs on the remote. Conflicts during merge are handled by the repository's standard merge resolution policies, not by the worktree isolation mechanism itself. ### Does worktree isolation duplicate the entire Git repository? No. Worktrees share the same underlying object database, making them lightweight compared to full clones. Only the working tree files and index are duplicated, minimizing disk overhead while maintaining complete isolation between agents. ### How does pi-subagents handle cleanup if an agent crashes? The `Worktree` class implements robust exception handling within its context manager in [`pi_subagents/worktree.py`](https://github.com/nicobailon/pi-subagents/blob/main/pi_subagents/worktree.py). Even if an agent crashes or raises an exception, the `__exit__` method ensures `git worktree remove` executes and the temporary branch is deleted, preventing resource leaks. ### Can agents share data between worktrees? While worktrees isolate Git state, they reside on the same filesystem. Agents can communicate through shared volumes or external caches, but all Git operations remain confined to their respective worktree directories, ensuring that `git add`, `git commit`, and `git checkout` operations never interfere with other agents.