Git worktrees are great. They stop at the repo boundary.

A developer argues that git worktrees, while ideal for isolating parallel AI coding agent sessions within a single repository, hit a hard structural boundary in polyrepo setups because the shared object store is scoped to one repo. The writeup walks through a three-repository API contract change (Rust api-service, TypeScript web-frontend, docs-site) and shows a roughly 60-line bash script that automates worktree creation and symlinks them into a unified workspace for agent sessions.

Git worktrees git worktree add have become an indispensable primitive in modern software engineering and agentic workflows. Most community articles explaining how to use git worktrees for AI coding agents get the core single-repository mechanics completely right: .git object store. Creating a worktree takes milliseconds because Git simply writes a lightweight .git/worktrees/<id in the main repository, avoiding the disk and network overhead of cloning full repository copies. index , HEAD ref pointer, and reflog. This allows multiple agent sessions to run in parallel on different feature branches without encountering lock contention or file collision. The shared object store is what makes a worktree cheap, and it is also what makes it stop at the repository it belongs to. For single-repository engineering, git worktrees provide an ideal local execution environment. The agent operates inside an isolated file tree, language servers index files correctly, build tools run natively, and git status tracks changes cleanly. However, modern software applications rarely reside in a single repository. The moment a software feature spans multiple repositories, the single-repo worktree model encounters a hard structural boundary. Consider a routine architectural task in a polyrepo ecosystem: modifying an API contract. The feature spans three distinct git repositories: api-service : The Rust backend implementing the updated endpoint payload. web-frontend : The TypeScript application consuming the API response. docs-site : The documentation repository hosting public API reference specs. To execute this change with an AI coding agent, you require a composite workspace configuration: feature-auth inside main inside Using raw git worktree commands manually requires executing a tedious multi-step sequence across three separate repository paths: Manual worktree creation across three repos git -C ~/repos/api-service worktree add -b feature-auth ../worktrees/api-feature-auth git -C ~/repos/web-frontend worktree add -b feature-auth ../worktrees/web-feature-auth git -C ~/repos/docs-site worktree add ../worktrees/docs-main main Create a temporary workspace directory and symlink worktrees mkdir -p ~/workspaces/feature-auth ln -s ~/worktrees/api-feature-auth ~/workspaces/feature-auth/api ln -s ~/worktrees/web-feature-auth ~/workspaces/feature-auth/web ln -s ~/worktrees/docs-main ~/workspaces/feature-auth/docs Executing these steps manually for every feature task is slow, repetitive, and error-prone. Consequently, developers build shell scripts to automate multi-repository worktree assembly. Here is a typical, 60-line bash script that developers construct to automate multi-repository worktree setup for AI agent sessions: bash /usr/bin/env bash set -euo pipefail FEATURE NAME="${1:-}" if -z "$FEATURE NAME" ; then echo "Error: Feature name required." echo "Usage: $0 <feature-name " exit 1 fi WORKSPACE DIR="$HOME/.workspaces/$FEATURE NAME" mkdir -p "$WORKSPACE DIR" declare -A REPOS= "api" ="$HOME/repos/api-service" "web" ="$HOME/repos/web-frontend" "docs" ="$HOME/repos/docs-site" echo "Initializing multi-repo worktrees for feature: $FEATURE NAME" for NAME in "${ REPOS @ }"; do REPO PATH="${REPOS $NAME }" TARGET WORKTREE="$REPO PATH/../worktrees/$NAME-$FEATURE NAME" if "$NAME" == "docs" ; then Read-only reference repository stays checked out on main echo "Creating reference worktree for $NAME on main..." git -C "$REPO PATH" worktree add "$TARGET WORKTREE" main 2 /dev/null || true else Feature repositories check out feature branch echo "Creating feature worktree for $NAME on branch $FEATURE NAME..." git -C "$REPO PATH" worktree add -b "$FEATURE NAME" "$TARGET WORKTREE" 2 /dev/null || true fi Symlink worktree into unified workspace folder ln -sfn "$TARGET WORKTREE" "$WORKSPACE DIR/$NAME" done Create combined harness instructions cat <<EOF "$WORKSPACE DIR/CLAUDE.md" Multi-Repo Workspace Context: $FEATURE NAME - api/: Rust backend service editable feature worktree - web/: TypeScript web application editable feature worktree - docs/: Documentation site reference context only, DO NOT EDIT EOF echo "Multi-repo workspace materialized at: $WORKSPACE DIR" cd "$WORKSPACE DIR" && claude This script automates worktree creation, symlinks the directories into a unified workspace folder, generates a basic CLAUDE.md , and launches the agent harness. While this script works for basic local demos, attempting to rely on it in production engineering environments reveals four fundamental limitations. While an ad-hoc shell script automates directory symlinking, it lacks the technical infrastructure required for reliable, safe multi-repository agent execution. | What it needs to do | What the script does instead | |---|---| | Guard writes to reference repos | Relies on a soft prompt rule | | Keep branches and lifecycle aligned | Leaves dirty and orphaned trees | | Materialise instructions | Dirties tracked files in each repo | | Deliver the feature | Pushes each branch on its own | The shell script creates worktrees on disk using standard user write permissions 0755 / 0644 . To restrict modifications in docs/ , the script relies exclusively on a text instruction inside CLAUDE.md : "docs/: reference context only, DO NOT EDIT" . Under high context load or multi-step reasoning tasks, language models non-deterministically violate prompt instructions. An agent fixing a broken build or lint error will edit files in docs/ directly, mutating git state in a reference repository. The script cannot enforce write restrictions at the operating system layer. When an agent session finishes or crashes, the script leaves active worktrees and branches dangling across multiple repository directories. If a session fails midway: .git/worktrees/ across individual repos. git worktree prune and delete orphaned feature branches. Furthermore, if branch creation fails in one repository e.g., due to an uncommitted conflict on main , the script leaves the workspace in a partially initialized, inconsistent state across repos without atomic rollback. The script injects instructions by writing a static CLAUDE.md file at the root of the workspace. However, real-world repositories already contain their own provider-native instruction files e.g., api/CLAUDE.md and web/CLAUDE.md . The script cannot merge or synthesize instructions across repositories. If the script writes instruction files directly inside individual repository worktrees, it leaves untracked, dirty files in git status that risk being accidentally committed by the agent. Once an agent completes changes across api/ and web/ , delivering the feature requires verifying status, pushing feature branches across multiple repositories, and establishing cross-repository pull request references. The shell script leaves delivery entirely to manual git operations. It cannot verify atomic feature readiness across mounted repositories, track which repositories were actually modified during the session, or trigger synchronized multi-repo branch pushes deliver . Note that multi-repo delivery coordinates push operations across repositories, rather than attempting complex dependency sorting or automated merge ordering. The central vulnerability of custom multi-repo worktree scripts is relying on LLM prompt compliance for write protection. Soft prompt instructions and software hooks inevitably fail under context saturation, complex agent reasoning, or raw shell command execution. Robust write protection requires enforcing file immutability at the operating system layer using POSIX file permission masks chmod . if mode & 0o222 = 0 { chmod path, mode & 0o222 ?; } In an orchestrated View Directory architecture: docs/ is mounted into the session workspace, write bits 0o222 are stripped recursively across its worktree files and directories via clear write bits . , or an automated code modifier—the operating system kernel rejects the write operation immediately with an EACCES Permission Denied error. u+w via restore write bits mode | 0o200 , permitting authorized modifications: chmod path, mode | 0o200 ?; By operating at the kernel permission layer, write enforcement remains absolute regardless of LLM prompt drift, context saturation, or tool execution style. Git worktrees provide the essential foundation for local agent workspaces, but scaling them across multiple repositories requires dedicated session orchestration rather than fragile shell scripts. How a View Dir combines those worktrees with a kernel-enforced write guard is covered in what a View Dir is https://ivar.run/docs/what-is-ivar , and the quickstart https://ivar.run/docs/quickstart walks through mounting your first one.