Agent Git Worktrees

Bare-repo Git worktree patterns for parallel agent workflows.

Important execution nuance: in some agent shell environments, a tool-level working directory is not reliably applied to child Git commands. That is not a problem with the worktree layout itself. Agents should prefer explicit command targeting such as git -C <worktree-path> ..., or git --git-dir <project>/.bare --work-tree <worktree-path> ... when operating from outside the repo.

This repository exists for one reason: make Git worktrees practical for multi-agent coding. The central recommendation is simple:

1. Use one bare repository as the shared Git database.
2. Use one branch per worktree.
3. Use one agent per worktree.
4. Never check out the same branch in multiple worktrees.

That gives you shared object storage, isolated working directories, and a layout that does not privilege one checkout as "the main repo".

Why This Layout

The recommended structure is:

project/
  .bare/
  main/                  or master/
  feat-search/
  feat-search-ui/
  feat-search-api/

.bare/ is the brain. Every sibling directory is just a checkout.

This is usually better than a single normal clone that also hosts .worktrees/ because:

• every worktree is equal
• there is no "special" checkout that hosts the others
• there is nothing extra to .gitignore
• the mental model stays clean for both humans and agents

Recommended Branch Model

Use this pattern when several agents work on one larger feature:

• main or master: trunk
• feat/search-redesign: integration branch for the feature
• feat/search-redesign-ui: agent branch
• feat/search-redesign-api: agent branch
• feat/search-redesign-tests: agent branch

Each agent branch starts from the feature branch, not directly from trunk.

Quick Start

PowerShell

Source the helpers:

. .\scripts\powershell\git-worktree.ps1

To make the helpers available in every PowerShell session, add a dot-source line to your PowerShell profile:

$gitWorktreeHelpers = "C:\path\to\agent-git-worktrees\scripts\powershell\git-worktree.ps1"
if (Test-Path $gitWorktreeHelpers) {
    . $gitWorktreeHelpers
}

Create a new managed repo:

gnew https://github.com/OWNER/REPO.git

Create a feature branch from trunk:

gwt feat/search-redesign -From main

If your shell is at project/ or project/.bare/, gwt feat/search-redesign works too and defaults the base to the repository default branch.

Create agent branches from the feature branch:

gwt feat/search-redesign-ui -From feat/search-redesign
gwt feat/search-redesign-api -From feat/search-redesign

List worktrees:

gwl

Remove a clean merged worktree:

gwrm feat/search-redesign-ui

When running from project/ or project/.bare/, pass the branch name explicitly to gwrm because there is no current checked-out worktree to infer it from.

Reset a managed repo to only the default branch worktree after confirming all other work is disposable:

gprune
gprune -Force

Without -Force, gprune prints a dry-run summary and exits non-zero. With -Force, it removes all non-default registered worktrees, deletes removed non-default local branches where possible, resets the default branch worktree to origin/<default-branch>, cleans untracked files, prunes worktree metadata, and removes stray top-level project entries so only .bare and <default-branch> remain.

Bash / Zsh

Source the helpers:

source ./scripts/bash/git-worktree.sh

The command surface is the same: gnew, gwt, gwl, gwrm, gprune. Bash also accepts the documented gwt <branch> -From <base> form. In Bash or Zsh, run the destructive reset as gprune --force.

Merge Flow

Merge agent branches into the feature branch from the feature worktree:

git -C ./feat/search-redesign merge feat/search-redesign-ui
git -C ./feat/search-redesign merge feat/search-redesign-api
git -C ./feat/search-redesign merge feat/search-redesign-tests

Then merge the feature branch into trunk:

git -C ./main merge feat/search-redesign

Explicit Git Targeting

When an agent is not certain it is truly running inside the intended worktree, use explicit targeting:

git -C <worktree-path> status --short --branch
git -C <worktree-path> rev-parse --path-format=absolute --git-common-dir
git --git-dir <project>/.bare --work-tree <worktree-path> push origin <branch>

Treat this as an execution-environment best practice, not as a reason to avoid worktrees.

Migration

If you already have a normal clone and want to move to the bare-repo layout, see docs/migration-guide.md.

For Windows/PowerShell, a migration script is included at scripts/powershell/migrate-repo-to-worktrees.ps1. It keeps a full sibling backup of the original repo before rebuilding the working layout.

Included Artifacts

• AGENTS.md: platform-neutral agent instructions
• docs/why-bare-repo-layout.md: rationale and tradeoffs
• docs/merge-and-cleanup.md: merge, cleanup, and conflict guidance
• scripts/powershell/git-worktree.ps1: PowerShell helpers
• scripts/powershell/migrate-repo-to-worktrees.ps1: migration helper
• scripts/bash/git-worktree.sh: Bash/Zsh helpers
• skills/codex/git-worktree-manager/SKILL.md: Codex skill version of this workflow

Safety Rules

1. Never share a branch across multiple worktrees.
2. Keep one agent per worktree.
3. Use explicit -From bases when creating agent branches from a feature branch.
4. Refuse to delete dirty worktrees unless the user explicitly wants destructive cleanup.
5. Keep backups when migrating existing repositories.
6. Prefer git -C <worktree-path> over plain git ... in agent shells where the current directory may not be what the tool claims.
7. Use gprune --force or gprune -Force only when the user clearly asks to discard all non-default worktrees and reset the project to the default branch only.

Manual gprune Test Checklist

Run the Bash helper smoke tests on macOS or Linux with:

./tests/bash/git-worktree-helper-tests.sh

Run the PowerShell helper smoke tests on Windows with:

.\tests\powershell\git-worktree-helper-tests.ps1

For manual verification, use a disposable local fixture and verify:

• dry-run exits non-zero and removes nothing
• forced cleanup works from the project root, .bare, the default worktree, and a feature worktree
• a missing default worktree is recreated at project/<default-branch>
• dirty non-default worktrees and external registered worktrees are removed
• stray top-level project files and folders are removed
• final output shows remaining registered worktrees, default branch status, default HEAD SHA, origin/<default-branch> SHA, and top-level project-root contents

License

MIT. See LICENSE.