![\"Git](\"https:\/\/www.kdnuggets.com\/wp-content\/uploads\/KDN-Shittu-Git-Worktrees-for-AI-Development-scaled.png\"\/)
\u00a0<\/p>\n
#\u00a0<\/span>Introduction<\/h2>\n\u00a0You might be working Claude Code on a function department. The agent has been working for twenty minutes, it has learn your codebase, constructed up context, and began making actual progress on the authentication rewrite. Then a Slack message seems: manufacturing is down, somebody wants a hotfix on fundamental, and so they want it now.<\/p>\n
Within the previous workflow, you stash your adjustments, swap branches, lose the whole lot your AI agent constructed up, repair the bug, push, swap again, and spend ten minutes getting the agent re-oriented to what it was doing. For those who had been working two brokers concurrently on the identical listing, the state of affairs is worse \u2014 each brokers touching package deal.json, each producing edits to the identical information, and the second writes silently, overwriting the primary. No warning. No error. Simply corrupted work you uncover an hour later when assessments fail in a method that is not sensible.<\/p>\n
Git worktrees remove this complete class of issues. They aren’t a brand new invention \u2014 the function has been in Git since model 2.5, launched in 2015 \u2014 however the AI coding wave of 2025\u20132026 made them important infrastructure. One .git listing, a number of working directories, every by itself department, every invisible to the others. Every AI agent will get its personal remoted workspace. The hotfix will get its personal workspace. Nothing collides.<\/p>\n
51% {of professional} builders now use AI instruments each day, however solely 17% of builders utilizing AI brokers say these instruments have improved group collaboration. The hole between these two numbers isn’t a tooling downside. It’s an infrastructure downside. Groups adopted AI brokers with out the workflow layer beneath. This information is that workflow layer.<\/p>\n
By the tip, you’ll know what worktrees are, learn how to set them up, learn how to run parallel AI brokers inside them with out chaos, and learn how to preserve them over the lifetime of a mission.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>What Git Worktrees Truly Are<\/h2>\n\u00a0<\/p>\n
A normal Git repository has one working listing \u2014 the folder the place your information reside and the place you edit code. To work on a unique department, you turn to it, which adjustments all of the information in that listing to match the department. When you’ve got uncommitted work, you stash it first. In case your AI agent is mid-task, you interrupt it.<\/p>\n
Git worktrees break this constraint. A worktree is a separate listing checked out from the identical repository. You may have as many as you want, every by itself department, all coexisting concurrently in your filesystem.<\/p>\n
\nmy-project\/ \u2190 fundamental worktree (department: fundamental)
\nmy-project-feat-auth\/ \u2190 linked worktree (department: feat\/auth)
\nmy-project-feat-api\/ \u2190 linked worktree (department: feat\/api)
\nmy-project-hotfix-login\/ \u2190 linked worktree (department: hotfix\/login)\n<\/div>\n\u00a0<\/p>\n
All 4 directories share the identical .git folder. They share historical past, objects, and commits. However every has its personal checked-out information, its personal index, and its personal working state. An agent enhancing information in my-project-feat-auth\/ can not see or contact something in my-project-feat-api\/. They’re bodily separate directories that occur to share a git backend.<\/p>\n
\u00a0![\"A](\"https:\/\/www.kdnuggets.com\/wp-content\/uploads\/KDN-Shittu-A-diagram-showing-one-git-folder-at-the-center-with-four-directory-boxes-branching-out-from-it-b.png\"\/)
\u00a0<\/p>\n
Why does this beat a number of clones? The naive different to worktrees is cloning the repository twice and dealing in several clone directories. This works, however it has actual prices: you duplicate your complete repository on disk, git historical past isn’t shared between clones, commits in a single clone aren’t instantly seen in one other, and there’s no coordination between them on the git layer. With worktrees, you clone as soon as. Each extra worktree provides solely the price of the checked-out information, not one other copy of the total historical past.<\/p>\n
The seven instructions that cowl the whole lot you must handle worktrees:<\/p>\n
\u00a0<\/p>\n
Command
\nWhat It Does<\/p>\n
git worktree add -b
\nCreate a brand new worktree on a brand new department<\/p>\n
git worktree add
\nTry an current department into a brand new worktree<\/p>\n
git worktree record
\nPresent all lively worktrees with their branches and commit hashes<\/p>\n
git worktree lock
\nForestall a worktree from being pruned (helpful whereas an agent is working)<\/p>\n
git worktree unlock
\nLaunch the lock<\/p>\n
git worktree take away
\nDelete a worktree cleanly (department is preserved)<\/p>\n
git worktree prune
\nClear up metadata for worktrees that had been manually deleted<\/p>\n
\u00a0<\/p>\n
That’s the full floor space. All the things else on this article is a workflow constructed on prime of those seven instructions.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Setting Up<\/h2>\n\u00a0Conditions: Git 2.5 or larger. Run git –version to test. Any trendy system (macOS, Linux, Home windows with WSL or Git Bash) ships with a model above 2.5.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 1: Beginning From a Clear Repository<\/h4>\nWorktrees work greatest when your fundamental department is clear. Commit or stash any in-progress work earlier than creating your first worktree.<\/p>\n
\n# Confirm you may have a clear working tree
\ngit standing
\n
\n# If there’s uncommitted work, commit it
\ngit add . && git commit -m “checkpoint: work in progress”\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 2: Creating Your First Worktree<\/h4>\n\n# Create a brand new worktree at ..\/myapp-feat-auth on a brand new department feat\/auth
\n# Exchange “myapp” along with your mission title and “feat\/auth” along with your department title
\ngit worktree add -b feat\/auth ..\/myapp-feat-auth fundamental
\n
\n# Confirm it was created
\ngit worktree record\n<\/div>\n\u00a0<\/p>\n
You need to see output like this:<\/p>\n
\n\/house\/person\/myapp abc1234 [main]
\n\/house\/person\/myapp-feat-auth abc1234 [feat\/auth]\n<\/div>\n\u00a0<\/p>\n
Each directories exist. Each comprise the identical information from the principle department. From this level, any adjustments you make in myapp-feat-auth\/ keep on feat\/auth and are fully remoted from fundamental.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 3: Setting Up the Setting within the New Worktree<\/h4>\nThat is the step most tutorials skip. A worktree is a brand new working listing. It doesn’t mechanically have your .env file, your put in node_modules, or your Python digital surroundings. It’s essential set these up explicitly.<\/p>\n
\ncd ..\/myapp-feat-auth
\n
\n# Copy surroundings information which can be gitignored
\n# .env, .env.native, and comparable information aren’t tracked in git –
\n# they won’t seem within the new worktree mechanically
\ncp ..\/myapp\/.env .env
\ncp ..\/myapp\/.env.native .env.native 2>\/dev\/null || true
\n
\n# Node.js mission: set up dependencies
\n# Every worktree is an unbiased working listing –
\n# node_modules from the mother or father doesn’t carry over
\nnpm set up
\n
\n# Python mission: create and activate a digital surroundings
\n# python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 4: Verifying the Worktree Is Remoted<\/h4>\n\n# From inside the brand new worktree
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0![\"A](\"https:\/\/www.kdnuggets.com\/wp-content\/uploads\/KDN-Shittu-A-flowchart-showing-the-hackathon-setup-b.png\"\/)
\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\u00a0<\/p>\n
A normal Git repository has one working listing \u2014 the folder the place your information reside and the place you edit code. To work on a unique department, you turn to it, which adjustments all of the information in that listing to match the department. When you’ve got uncommitted work, you stash it first. In case your AI agent is mid-task, you interrupt it.<\/p>\n
Git worktrees break this constraint. A worktree is a separate listing checked out from the identical repository. You may have as many as you want, every by itself department, all coexisting concurrently in your filesystem.<\/p>\n
\nmy-project-feat-auth\/ \u2190 linked worktree (department: feat\/auth)
\nmy-project-feat-api\/ \u2190 linked worktree (department: feat\/api)
\nmy-project-hotfix-login\/ \u2190 linked worktree (department: hotfix\/login)\n<\/div>\n
\u00a0<\/p>\n
All 4 directories share the identical .git folder. They share historical past, objects, and commits. However every has its personal checked-out information, its personal index, and its personal working state. An agent enhancing information in my-project-feat-auth\/ can not see or contact something in my-project-feat-api\/. They’re bodily separate directories that occur to share a git backend.<\/p>\n
\u00a0\u00a0<\/p>\n
Why does this beat a number of clones? The naive different to worktrees is cloning the repository twice and dealing in several clone directories. This works, however it has actual prices: you duplicate your complete repository on disk, git historical past isn’t shared between clones, commits in a single clone aren’t instantly seen in one other, and there’s no coordination between them on the git layer. With worktrees, you clone as soon as. Each extra worktree provides solely the price of the checked-out information, not one other copy of the total historical past.<\/p>\n
The seven instructions that cowl the whole lot you must handle worktrees:<\/p>\n
\u00a0<\/p>\n
Command
\nWhat It Does<\/p>\n
git worktree add -b
\nCreate a brand new worktree on a brand new department<\/p>\n
git worktree add
\nTry an current department into a brand new worktree<\/p>\n
git worktree record
\nPresent all lively worktrees with their branches and commit hashes<\/p>\n
git worktree lock
\nForestall a worktree from being pruned (helpful whereas an agent is working)<\/p>\n
git worktree unlock
\nLaunch the lock<\/p>\n
git worktree take away
\nDelete a worktree cleanly (department is preserved)<\/p>\n
git worktree prune
\nClear up metadata for worktrees that had been manually deleted<\/p>\n
\u00a0<\/p>\n
That’s the full floor space. All the things else on this article is a workflow constructed on prime of those seven instructions.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Setting Up<\/h2>\n\u00a0Conditions: Git 2.5 or larger. Run git –version to test. Any trendy system (macOS, Linux, Home windows with WSL or Git Bash) ships with a model above 2.5.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 1: Beginning From a Clear Repository<\/h4>\nWorktrees work greatest when your fundamental department is clear. Commit or stash any in-progress work earlier than creating your first worktree.<\/p>\n
\n# Confirm you may have a clear working tree
\ngit standing
\n
\n# If there’s uncommitted work, commit it
\ngit add . && git commit -m “checkpoint: work in progress”\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 2: Creating Your First Worktree<\/h4>\n\n# Create a brand new worktree at ..\/myapp-feat-auth on a brand new department feat\/auth
\n# Exchange “myapp” along with your mission title and “feat\/auth” along with your department title
\ngit worktree add -b feat\/auth ..\/myapp-feat-auth fundamental
\n
\n# Confirm it was created
\ngit worktree record\n<\/div>\n\u00a0<\/p>\n
You need to see output like this:<\/p>\n
\n\/house\/person\/myapp abc1234 [main]
\n\/house\/person\/myapp-feat-auth abc1234 [feat\/auth]\n<\/div>\n\u00a0<\/p>\n
Each directories exist. Each comprise the identical information from the principle department. From this level, any adjustments you make in myapp-feat-auth\/ keep on feat\/auth and are fully remoted from fundamental.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 3: Setting Up the Setting within the New Worktree<\/h4>\nThat is the step most tutorials skip. A worktree is a brand new working listing. It doesn’t mechanically have your .env file, your put in node_modules, or your Python digital surroundings. It’s essential set these up explicitly.<\/p>\n
\ncd ..\/myapp-feat-auth
\n
\n# Copy surroundings information which can be gitignored
\n# .env, .env.native, and comparable information aren’t tracked in git –
\n# they won’t seem within the new worktree mechanically
\ncp ..\/myapp\/.env .env
\ncp ..\/myapp\/.env.native .env.native 2>\/dev\/null || true
\n
\n# Node.js mission: set up dependencies
\n# Every worktree is an unbiased working listing –
\n# node_modules from the mother or father doesn’t carry over
\nnpm set up
\n
\n# Python mission: create and activate a digital surroundings
\n# python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 4: Verifying the Worktree Is Remoted<\/h4>\n\n# From inside the brand new worktree
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
Worktrees work greatest when your fundamental department is clear. Commit or stash any in-progress work earlier than creating your first worktree.<\/p>\n
\ngit standing
\n
\n# If there’s uncommitted work, commit it
\ngit add . && git commit -m “checkpoint: work in progress”\n<\/div>\n
\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 2: Creating Your First Worktree<\/h4>\n\n# Create a brand new worktree at ..\/myapp-feat-auth on a brand new department feat\/auth
\n# Exchange “myapp” along with your mission title and “feat\/auth” along with your department title
\ngit worktree add -b feat\/auth ..\/myapp-feat-auth fundamental
\n
\n# Confirm it was created
\ngit worktree record\n<\/div>\n\u00a0<\/p>\n
You need to see output like this:<\/p>\n
\n\/house\/person\/myapp abc1234 [main]
\n\/house\/person\/myapp-feat-auth abc1234 [feat\/auth]\n<\/div>\n\u00a0<\/p>\n
Each directories exist. Each comprise the identical information from the principle department. From this level, any adjustments you make in myapp-feat-auth\/ keep on feat\/auth and are fully remoted from fundamental.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 3: Setting Up the Setting within the New Worktree<\/h4>\nThat is the step most tutorials skip. A worktree is a brand new working listing. It doesn’t mechanically have your .env file, your put in node_modules, or your Python digital surroundings. It’s essential set these up explicitly.<\/p>\n
\ncd ..\/myapp-feat-auth
\n
\n# Copy surroundings information which can be gitignored
\n# .env, .env.native, and comparable information aren’t tracked in git –
\n# they won’t seem within the new worktree mechanically
\ncp ..\/myapp\/.env .env
\ncp ..\/myapp\/.env.native .env.native 2>\/dev\/null || true
\n
\n# Node.js mission: set up dependencies
\n# Every worktree is an unbiased working listing –
\n# node_modules from the mother or father doesn’t carry over
\nnpm set up
\n
\n# Python mission: create and activate a digital surroundings
\n# python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 4: Verifying the Worktree Is Remoted<\/h4>\n\n# From inside the brand new worktree
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\n# Exchange “myapp” along with your mission title and “feat\/auth” along with your department title
\ngit worktree add -b feat\/auth ..\/myapp-feat-auth fundamental
\n
\n# Confirm it was created
\ngit worktree record\n<\/div>\n
\u00a0<\/p>\n
You need to see output like this:<\/p>\n
\n\/house\/person\/myapp-feat-auth abc1234 [feat\/auth]\n<\/div>\n
\u00a0<\/p>\n
Each directories exist. Each comprise the identical information from the principle department. From this level, any adjustments you make in myapp-feat-auth\/ keep on feat\/auth and are fully remoted from fundamental.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 3: Setting Up the Setting within the New Worktree<\/h4>\nThat is the step most tutorials skip. A worktree is a brand new working listing. It doesn’t mechanically have your .env file, your put in node_modules, or your Python digital surroundings. It’s essential set these up explicitly.<\/p>\n
\ncd ..\/myapp-feat-auth
\n
\n# Copy surroundings information which can be gitignored
\n# .env, .env.native, and comparable information aren’t tracked in git –
\n# they won’t seem within the new worktree mechanically
\ncp ..\/myapp\/.env .env
\ncp ..\/myapp\/.env.native .env.native 2>\/dev\/null || true
\n
\n# Node.js mission: set up dependencies
\n# Every worktree is an unbiased working listing –
\n# node_modules from the mother or father doesn’t carry over
\nnpm set up
\n
\n# Python mission: create and activate a digital surroundings
\n# python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt\n<\/div>\n\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 4: Verifying the Worktree Is Remoted<\/h4>\n\n# From inside the brand new worktree
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\n
\n# Copy surroundings information which can be gitignored
\n# .env, .env.native, and comparable information aren’t tracked in git –
\n# they won’t seem within the new worktree mechanically
\ncp ..\/myapp\/.env .env
\ncp ..\/myapp\/.env.native .env.native 2>\/dev\/null || true
\n
\n# Node.js mission: set up dependencies
\n# Every worktree is an unbiased working listing –
\n# node_modules from the mother or father doesn’t carry over
\nnpm set up
\n
\n# Python mission: create and activate a digital surroundings
\n# python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt\n<\/div>\n
\u00a0<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Step 4: Verifying the Worktree Is Remoted<\/h4>\n\n# From inside the brand new worktree
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\ngit department
\n# Ought to present: * feat\/auth
\n
\n# Make a take a look at change
\necho “\/\/ take a look at” >> test-isolation.js
\ngit standing
\n# Solely exhibits the change on this worktree
\n
\n# Change to the principle listing and confirm it’s unaffected
\ncd ..\/myapp
\ngit standing
\n# Clear — the test-isolation.js change is invisible right here
\nls test-isolation.js 2>\/dev\/null || echo “Not right here — isolation confirmed”\n<\/div>\n
\u00a0<\/p>\n
That’s all you must get began. The worktree is reside. Any agent you open in that listing operates solely on feat\/auth.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>A Actual-World Case Examine<\/h2>\n\u00a0<\/p>\n
The clearest documented instance of git worktrees used for AI-driven parallel improvement comes from the Microsoft International Hackathon 2025.<\/p>\n
Tamir Dresher, an engineering lead, confronted an issue that everybody constructing with AI brokers finally hits: too many options, too little time, and no technique to work on a couple of factor directly with out fixed context-switching. Creating a number of clones of the repository was cumbersome. Switching branches destroyed the AI agent’s context. One thing needed to change.<\/p>\n
The answer was to make use of git worktrees to create what Dresher described as a digital AI improvement group. Every function bought its personal worktree. Every worktree bought its personal VS Code window. Every window ran its personal AI agent. Dresher’s position shifted from developer to tech lead: scoping duties, reviewing output, guiding brokers that bought caught, and merging completed work.<\/p>\n
The setup regarded like this:<\/p>\n
\nmyapp\/ \u2190 fundamental window: coordination and opinions
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\nmyapp-feat-authentication\/ \u2190 Agent 1: implementing OAuth2 circulate
\nmyapp-feat-api-endpoints\/ \u2190 Agent 2: constructing REST endpoints
\nmyapp-bugfix-login-crash\/ \u2190 Agent 3: fixing manufacturing bug\n<\/div>\n
\u00a0<\/p>\n
Every VS Code window was fully unbiased. Language servers, linters, and take a look at runners run per window. The brokers by no means touched one another’s information. When Agent 1 completed, Dresher reviewed the diff, authorised it, and opened a pull request (PR) from that department \u2014 the identical workflow as reviewing a PR from a human engineer.<\/p>\n
Three concrete benefits Dresher documented from the hackathon:<\/p>\n
No context loss. Every AI agent maintained full context of its particular activity. Switching between options meant switching VS Code home windows, not branches, not stashes, not agent restarts. The agent’s understanding of what it was constructing stayed intact.
\nCompletely different instruments for various jobs. As a result of every window was unbiased, Dresher ran Roo in a single window for speedy function improvement and GitHub Copilot with Visible Studio in one other for debugging complicated points. Mixing instruments throughout duties was trivial.
\nClear department administration. If a function wanted to be deserted, closing the window and deleting the worktree took ten seconds. The opposite brokers had been unaffected.<\/p>\n
\u00a0\u00a0<\/p>\n
The sample that emerged from this hackathon is now a documented greatest follow throughout the AI coding neighborhood.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Operating Parallel AI Brokers With Worktrees<\/h2>\n\u00a0<\/p>\n
The mechanics of the total parallel workflow have 4 levels: arrange the worktrees, give every agent its context, run the brokers, and checkpoint recurrently.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 1: Scripting the Worktree Creation<\/h4>\nDon’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
Don’t create worktrees manually every time. A script ensures each worktree will get the identical setup \u2014 surroundings information, dependency set up, and a clear place to begin.<\/p>\n
Conditions: Git 2.5+, Bash (macOS\/Linux\/WSL)<\/p>\n
The way to run: Save as create-worktree.sh in your mission root, run chmod +x create-worktree.sh, then .\/create-worktree.sh feat\/auth-redesign fundamental.<\/p>\n
\n# create-worktree.sh
\n# Creates an remoted worktree for one AI agent activity
\n# Utilization: .\/create-worktree.sh [base-branch]
\n# Instance: .\/create-worktree.sh feat\/auth-redesign fundamental
\n
\nset -euo pipefail
\n
\nBRANCH=”${1:?Utilization: $0 [base-branch]}”
\nBASE=”${2:-main}”
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\n
\n# Exchange slashes in department title with dashes for listing naming
\n# feat\/auth-redesign turns into feat-auth-redesign within the path
\nWORKTREE_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${BRANCH\/\/\/\/-}”
\n
\necho “Creating worktree for department: $BRANCH”
\necho “Base department: $BASE”
\necho “Worktree path: $WORKTREE_PATH”
\n
\n# Fetch newest so the brand new department begins from the present distant state
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\n# Create the worktree on a brand new department from the bottom department
\n# Falls again to testing an current department if -b fails
\ngit worktree add -b “$BRANCH” “$WORKTREE_PATH” “$BASE” 2>\/dev\/null ||
\n git worktree add “$WORKTREE_PATH” “$BRANCH”
\n
\n# Copy non-tracked surroundings information into the worktree
\n# These are gitignored, so they don’t carry over mechanically
\nfor f in .env .env.native .env.improvement .env.take a look at; do
\n if [ -f “$REPO_ROOT\/$f” ]; then
\n cp “$REPO_ROOT\/$f” “$WORKTREE_PATH\/$f”
\n echo “Copied $f”
\n fi
\nfinished
\n
\n# Node.js: set up dependencies within the new working listing
\nif [ -f “$WORKTREE_PATH\/package.json” ]; then
\n echo “Putting in Node dependencies…”
\n (cd “$WORKTREE_PATH” && npm set up –silent 2>\/dev\/null ||
\n echo “(npm set up skipped — run it manually within the worktree)”)
\nfi
\n
\n# Python: remind the developer to arrange their surroundings
\nif [ -f “$WORKTREE_PATH\/requirements.txt” ] || [ -f “$WORKTREE_PATH\/pyproject.toml” ]; then
\n echo “Python mission detected.”
\n echo “Run within the new worktree:”
\n echo ” python -m venv .venv && supply .venv\/bin\/activate && pip set up -r necessities.txt”
\nfi
\n
\necho “”
\necho “Worktree prepared. Open it in your IDE and begin your agent:”
\necho ” cd $WORKTREE_PATH”\n<\/div>\n
\u00a0<\/p>\n
What this does: The script creates the worktree, copies gitignored surroundings information throughout (the commonest setup failure), and runs dependency set up within the new listing. The ${BRANCH\/\/\/\/-} substitution safely converts department names like feat\/auth into filesystem-friendly listing names like feat-auth. The fallback on line 23 handles the case the place the department already exists remotely.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 2: Setting Up the AGENTS.md Context File<\/h4>\nThe only most necessary factor you are able to do to enhance agent output is give every agent a transparent, written context file. Peer-reviewed analysis at ICSE 2026 confirmed that incorporating architectural documentation into agent context produces measurable good points in purposeful correctness, architectural conformance, and code modularity. The AGENTS.md file is the way you ship that context reliably, at scale, throughout each session.<\/p>\n
Create this file in your mission root and commit it. Each agent reads it on session begin. Completely different instruments learn totally different filenames \u2014 AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), AGENTS.md (generic) \u2014 however the content material issues greater than the title.<\/p>\n
\n# AGENTS.md
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\n# Create a worktree and begin a Claude Code session inside it
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# .worktreeinclude — place in your repo root
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\n# Venture context for AI coding brokers
\n# Commit this to your repository root.
\n# Each agent that opens this mission reads it first.
\n
\n## Venture Overview
\nNode.js\/TypeScript REST API with a React frontend.
\nStack: Node 20, Categorical 5, Prisma ORM, PostgreSQL, React 18, Vite.
\n
\n## Construct and Take a look at Instructions
\nnpm run dev # begin dev server on port 3000
\nnpm run construct # manufacturing construct to dist\/
\nnpm run take a look at # run all assessments (Vitest)
\nnpm run take a look at:watch # watch mode
\nnpm run lint # ESLint and Prettier test
\nnpm run db:migrate # run pending Prisma migrations
\nnpm run db:seed # seed improvement knowledge
\n
\n## Structure
\n– API routes: src\/routes\/ one file per useful resource
\n– Enterprise logic: src\/companies\/ by no means in route handlers
\n– Database entry: src\/repositories\/ by no means name Prisma immediately from companies
\n– Shared sorts: src\/sorts\/index.ts
\n
\n## Conventions
\n– All exported capabilities require JSDoc feedback
\n– No console.log in dedicated code — use src\/utils\/logger.ts
\n– Error dealing with: throw typed errors from companies, catch in route handlers
\n– Department naming: feat\/, repair\/, refactor\/
\n
\n## Prohibited Zones — Do NOT modify except explicitly instructed to
\n– src\/auth\/ (safety group possession, separate evaluate course of)
\n– prisma\/migrations\/ (solely modify by way of npm run db:migrate)
\n– .env information (by no means commit, by no means learn exterior config\/)
\n
\n## Present Worktree Job
\nJob: [FILL IN before starting the agent]
\nDepartment: [FILL IN]
\nAcceptance standards: [FILL IN]\n<\/div>\n
\u00a0<\/p>\n
The underside part is what makes this file work per-worktree. Each time you create a brand new worktree, open AGENTS.md and fill in these three strains earlier than beginning the agent. This scopes the agent’s work exactly and prevents it from wandering into areas it mustn’t contact.<\/p>\n
For Claude Code particularly, the native -w flag handles worktree creation and session begin in a single command:<\/p>\n
\nclaude –worktree feat\/auth-redesign
\n
\n# Brief kind
\nclaude -w feat\/auth-redesign
\n
\n# With tmux panes for split-screen visibility
\nclaude -w feat\/auth-redesign –tmux\n<\/div>\n
\u00a0<\/p>\n
claude –worktree creates .claude\/worktrees\/feat-auth-redesign\/ on a department referred to as worktree-feat-auth-redesign, then begins the session inside it. The .worktreeinclude file (gitignore syntax) controls which gitignored information are mechanically copied into new worktrees:<\/p>\n
\n# Information to repeat into each new worktree on creation
\n.env
\n.env.native
\n.env.improvement\n<\/div>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Stage 3: Operating A number of Brokers at As soon as<\/h4>\nWhenever you want three or 4 brokers working concurrently, scripting your complete setup saves time and ensures consistency.<\/p>\n
The way to run: Save as parallel-setup.sh, run chmod +x parallel-setup.sh, then .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\n# parallel-setup.sh
\n# Creates N worktrees for N parallel AI brokers in a single command
\n# Utilization: .\/parallel-setup.sh <\/p>\n
…
\n# Instance: .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard
\n
\nset -euo pipefail
\n
\nif [ $# -eq 0 ]; then
\n echo “Utilization: $0 <\/p>\n
… “
\n echo “Instance: $0 feat\/auth feat\/api feat\/dashboard”
\n exit 1
\nfi
\n
\nREPO_ROOT=”$(git rev-parse –show-toplevel)”
\nREPO_NAME=”$(basename “$REPO_ROOT”)”
\nMAIN_BRANCH=”fundamental”
\n
\necho “Organising ${#@} parallel worktrees…”
\ngit fetch origin 2>\/dev\/null || echo “(no distant — skipping fetch)”
\n
\nfor BRANCH in “$@”; do
\n SAFE=”${BRANCH\/\/\/\/-}”
\n WT_PATH=”${REPO_ROOT}\/..\/${REPO_NAME}-${SAFE}”
\n
\n if [ -d “$WT_PATH” ]; then
\n echo “Already exists: $WT_PATH (skipping)”
\n proceed
\n fi
\n
\n # Create worktree on a brand new department from fundamental
\n git worktree add -b “$BRANCH” “$WT_PATH” “$MAIN_BRANCH” 2>\/dev\/null ||
\n git worktree add “$WT_PATH” “$BRANCH”
\n
\n # Copy surroundings information
\n for f in .env .env.native; do
\n [ -f “$REPO_ROOT\/$f” ] && cp “$REPO_ROOT\/$f” “$WT_PATH\/$f”
\n finished
\n
\n echo “Created: $WT_PATH (department: $BRANCH)”
\nfinished
\n
\necho “”
\necho “All worktrees:”
\ngit worktree record
\necho “”
\necho “Open every path in a separate terminal or IDE window and begin your agent.”
\necho “Bear in mind to fill within the Job part of AGENTS.md in every worktree.”<\/p>\n<\/div>\n
\u00a0<\/p>\n
What this does: One command produces all of the worktrees with surroundings information copied. Operating .\/parallel-setup.sh feat\/auth feat\/api feat\/dashboard offers you three remoted working directories in underneath 5 seconds. Open every in its personal terminal tab, fill in AGENTS.md, and begin the brokers.<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Retaining Worktrees From Drifting<\/h2>\n\u00a0The largest long-term failure mode isn’t conflicts at creation time \u2014 it’s drift. A worktree that runs for 3 days with out syncing to fundamental accumulates divergence that makes merging a mission in itself.<\/p>\n
Practitioners utilizing Claude Code with worktrees in manufacturing are clear on this: after finishing a checkpoint, pull and merge updates from the principle department \u2014 this prevents the worktree from drifting too far, which might end in large, hard-to-resolve conflicts. The advice is to sync on the finish of each vital agent session, not simply earlier than the PR.<\/p>\n
The best technique is rebase, not merge. Rebasing writes your department’s commits on prime of the newest fundamental, which retains the historical past linear and makes the PR diff clear.<\/p>\n
The way to run: Save as sync-worktree.sh, run chmod +x sync-worktree.sh, then run .\/sync-worktree.sh from inside any worktree listing.<\/p>\n
\n#!\/usr\/bin\/env bash
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n# Contained in the worktree, after the agent finishes its activity
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\n# sync-worktree.sh
\n# Rebases the present worktree department onto the newest fundamental
\n# Run at checkpoints to stop department drift
\n# Utilization (from contained in the worktree): .\/sync-worktree.sh [main-branch-name]
\n# Instance: .\/sync-worktree.sh fundamental
\n
\nset -euo pipefail
\n
\nMAIN_BRANCH=”${1:-main}”
\nCURRENT_BRANCH=”$(git rev-parse –abbrev-ref HEAD)”
\n
\nif [ “$CURRENT_BRANCH” = “$MAIN_BRANCH” ]; then
\n echo “Already on $MAIN_BRANCH — nothing to sync.”
\n exit 0
\nfi
\n
\necho “Syncing ‘$CURRENT_BRANCH’ onto ‘$MAIN_BRANCH’…”
\n
\n# Reject if there’s uncommitted work — rebase requires a clear state
\nif ! git diff –quiet || ! git diff –cached –quiet; then
\n echo “ERROR: Uncommitted adjustments detected.”
\n echo “Commit your progress first:”
\n echo ” git add . && git commit -m ‘checkpoint: agent progress'”
\n exit 1
\nfi
\n
\n# Fetch the newest distant state
\ngit fetch origin
\n
\n# Rebase this department onto the newest fundamental
\n# –autostash handles minor working tree variations mechanically
\ngit rebase “origin\/$MAIN_BRANCH” –autostash
\n
\necho “”
\necho “Finished. ‘$CURRENT_BRANCH’ is updated with origin\/$MAIN_BRANCH.”
\necho “”
\necho “When able to push:”
\necho ” git push –force-with-lease”
\necho “”
\necho “Word: –force-with-lease is safer than –force.”
\necho “It refuses to push if another person pushed to this department since your final fetch.”\n<\/div>\n
\u00a0<\/p>\n
What this does: The uncommitted-changes test earlier than the rebase is a vital security measure. A rebase on a unclean tree produces a complicated state. –autostash handles minor variations. –force-with-lease on push is safer than –force as a result of it refuses to overwrite distant work you haven’t seen but.<\/p>\n
The complete merge lifecycle from agent completion to merged PR:<\/p>\n
\n
\n# 1. Commit the agent’s work
\ngit add .
\ngit commit -m “feat: implement OAuth2 + PKCE auth circulate”
\n
\n# 2. Sync with fundamental earlier than opening a PR
\n.\/sync-worktree.sh
\n
\n# 3. Run assessments to confirm nothing broke within the sync
\nnpm run take a look at
\n
\n# 4. Push the department
\ngit push –force-with-lease origin feat\/auth-redesign
\n
\n# 5. Open a PR by way of GitHub CLI or the net interface
\ngh pr create
\n –title “feat: OAuth2 + PKCE authentication”
\n –body “Implements OAuth2 per docs\/auth-spec.md. All assessments cross.”
\n
\n# 6. After the PR merges, clear up
\ncd ..\/myapp
\n.\/cleanup-worktree.sh feat\/auth-redesign\n<\/div>\n
\u00a0<\/p>\n
#\u00a0<\/span>The Full Command Reference<\/h2>\n\u00a0Each git worktree command with actual examples. Preserve this part open whereas constructing your first workflow.<\/p>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Creating Worktrees<\/h4>\n\n# Create a worktree on a brand new department from fundamental
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\ngit worktree add -b feat\/funds ..\/myapp-payments fundamental
\n
\n# Try an current department into a brand new worktree
\ngit worktree add ..\/myapp-feat-auth feat\/auth
\n
\n# Indifferent HEAD — helpful for reproducing a bug at a particular commit
\ngit worktree add –detach ..\/myapp-debug abc1234
\n
\n# Monitor a distant department immediately
\ngit worktree add ..\/myapp-hotfix origin\/hotfix\/login-crash\n<\/div>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Inspecting and Managing<\/h4>\n\n# Present all worktrees with path, commit hash, and department title
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\ngit worktree record
\n
\n# Machine-readable output to be used in scripts
\ngit worktree record –porcelain
\n
\n# Lock a worktree so prune doesn’t take away it
\n# Use whereas an agent is working to guard in opposition to unintentional cleanup
\ngit worktree lock ..\/myapp-feat-auth –reason “agent-running”
\n
\n# Launch the lock
\ngit worktree unlock ..\/myapp-feat-auth
\n
\n# Transfer a worktree listing (shut any open editors first)
\ngit worktree transfer ..\/myapp-feat-auth ..\/worktrees\/auth-redesign\n<\/div>\n
\u00a0<\/p>\n
\/\/\u00a0<\/span>Cleanup<\/h4>\n\n# Take away a worktree cleanly — the department is preserved in git
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\ngit worktree take away ..\/myapp-feat-auth
\n
\n# Power take away even with uncommitted adjustments
\n# Solely use this when you’re sure the work will be discarded
\ngit worktree take away –force ..\/myapp-feat-auth
\n
\n# Clear up metadata for worktrees manually deleted with rm -rf
\ngit worktree prune
\n
\n# Preview what can be pruned with out really pruning
\ngit worktree prune –dry-run
\n
\n# Repair worktree references after shifting the .git listing
\ngit worktree restore\n<\/div>\n
\u00a0<\/p>\n
#\u00a0<\/span>Frequent Errors and Fixes<\/h2>\n\u00a0<\/p>\n
Error Message
\nTrigger
\nRepair<\/p>\n
deadly: ‘feat\/auth’ is already checked out
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
deadly: already exists
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
error: ‘…’ is a fundamental worktree
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
error: worktree has modified information
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
Worktree seems in git worktree record after rm -rf
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0<\/p>\n
#\u00a0<\/span>Conclusion<\/h2>\n\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n
\nTrigger
\nRepair<\/p>\n
\nDepartment in use by one other worktree
\nUse a unique department, or take away the prevailing worktree first<\/p>\n
\nGoal listing exists
\nDelete it or select a unique path<\/p>\n
\nTried to take away the principle checkout
\nSolely linked worktrees will be eliminated<\/p>\n
\nUncommitted adjustments current
\nCommit the work, or use –force to discard<\/p>\n
\nMetadata not cleaned up
\nRun git worktree prune<\/p>\n
\u00a0Git worktrees aren’t superior Git arcana. They’re a core infrastructure primitive that grew to become important the second AI coding brokers began working in parallel on the identical codebases.<\/p>\n
The workflow on this article isn’t theoretical. It’s what Tamir Dresher’s group ran on the Microsoft International Hackathon. It’s what practitioners with Claude Code, Cursor, and Codex are documenting throughout GitHub and Medium proper now. It’s the sample the agentic coding neighborhood has converged on for one motive: it’s the easiest factor that reliably solves the issue it was constructed to unravel.<\/p>\n
The setup value is low. The 4 scripts on this article cowl the total lifecycle \u2014 create, sync, and clear up \u2014 in about 120 strains of bash. The conceptual mannequin is easy: one activity, one department, one worktree, one agent. The payoff is you can run a number of brokers in parallel with out spending your afternoon untangling conflicts that neither agent created deliberately.<\/p>\n
In case you are already utilizing AI coding instruments and never utilizing worktrees, set them up in your subsequent mission. The create-worktree.sh script is a ten-second begin. In case you are constructing a group workflow round AI brokers, AGENTS.md and the parallel setup script transfer you from ad-hoc periods to a repeatable course of that scales.<\/p>\n
The mannequin writes the code. Your job is to create the circumstances the place it will possibly do this cleanly, in parallel, with out getting in its personal method.\u00a0\u00a0<\/p>\n
Shittu Olumide is a software program engineer and technical author enthusiastic about leveraging cutting-edge applied sciences to craft compelling narratives, with a eager eye for element and a knack for simplifying complicated ideas. You can even discover Shittu on Twitter.<\/p>\n<\/p><\/div>\n