Investigating Git Worktrees and Worktrunk for AI Agents

When several AI agents work on different tasks at the same time, separate working directories as well as branch names.

Sharing one directory mixes uncommitted changes, generated output, dependencies, and development servers.

I find it clearer to examine native Git worktrees as the boundary for parallel work and Worktrunk as lifecycle management.

A branch does not isolate a working directory

Branch-only workflows in one directory share:

Uncommitted work from the previous task
Files another agent is editing
node_modules and build caches
.env files and service endpoints
Development-server ports
Running processes

A person watching the terminal may notice some of these collisions.

AI agents can change files and run commands while the terminal is unattended.

Do not make continuous human awareness of branch state the safety boundary.

What Git worktree provides

Git’s official documentation describes associating multiple working trees with one repository.

Each worktree has its own working tree, HEAD, and index, so different branches can be checked out at once.

The minimal form is:

git worktree add -b feature-auth ../repo.feature-auth main
git worktree list

After review and integration, inspect the target worktree and branch before cleaning them up.

git worktree remove ../repo.feature-auth
git branch -d feature-auth

A worktree is not a complete repository copy.

It shares Git objects while separating the working tree and index, which also means that the same branch cannot normally be checked out in multiple worktrees.

If a directory was deleted directly, inspect git worktree list for stale metadata and use git worktree prune when appropriate.

For locations that are not always mounted, also consider git worktree lock.

What Worktrunk adds

Native worktrees require separate commands for paths, branches, integration, and cleanup.

Worktrunk organizes this lifecycle around branch names.

The first official entry points to inspect are:

wt switch --create feature-auth
wt list
wt merge main

Depending on the installed version and configuration, wt merge can commit, squash, rebase, and remove a worktree.

Inspect the diff, uncommitted changes, and command help before running it.

Creation and removal hooks, port allocation, and AI-command execution are available too.

Start with creation, listing, and explicit integration, then add only automation that solves a real problem.

Define the unit that launches an agent

Assign each agent one working directory and one instruction.

A command close to the official examples is:

wt switch --create --execute codex feature-a -- 'Add authentication tests'

The --execute arguments and agent CLI depend on the environment.

The important rule is to avoid multiple writers in one worktree.

Separate worktrees do not prevent integration conflicts when two agents change the same API contract or configuration file.

Agree on shared interfaces and integration order before parallelizing.

Protect main as the baseline

Use main to inspect the integrated baseline and as the starting point for new worktrees.

Do not begin agent work directly on main.

Even a small commit-targeted change should use a task worktree.

Project rules should state at least:

Do not edit main directly
Use one worktree per parallel task
Do not change files in another worktree
Do not run git reset --hard or broad deletion
Review diffs and verification results before integration
Do not blindly copy .env files or secrets

These rules apply to people as well as agents.

Manage state outside the worktree

Worktrees separate files, but not every part of the development environment.

Dependencies

Creating Node.js node_modules or Rust target in every worktree increases setup cost.

Shared caches can improve speed, but may mix artifacts across branches.

Start with isolated setup and validate sharing only after setup time becomes a problem.

`.env`

An ignored .env can still contain database endpoints and API keys.

If it must be copied, use low-privilege development credentials only.

A safe test environment per worktree is preferable to distributing production credentials.

Ports

Parallel development servers collide when they all bind to port 3000.

Derive ports from branch names, use Worktrunk’s port allocation, or prohibit agents from starting servers.

Choose the policy before starting parallel work.

Make integration and cleanup part of review

Do not merge agent output into main blindly.

At minimum:

Inspect the worktree diff
Separate committed and uncommitted changes
Run lint, tests, and the build in the worktree
Check scope and generated files
Integrate through a pull request or local merge
Remove obsolete worktrees and branches

Check wt list and git worktree list periodically.

Forgotten worktrees, processes, and branches make the boundaries of parallel work harder to understand.

Summary

Git worktrees are valuable not only for opening several branches, but for making responsibility a directory-level boundary.

Worktrunk shortens creation, listing, integration, and removal.

.env files, ports, dependencies, and credentials still need separate design.

Native Git worktrees alone provide the foundation needed to protect main during parallel AI-agent work.