How Git Worktree Enables Parallel Agent‑Driven Development

Agent Coding is changing how we build software and use git worktree, filling a missing link for parallel execution.

Method: Structured Workflow

The author describes developing an open‑source, usage‑based billing platform built with React front‑end and Rails API in an event‑driven architecture. To stay on track, they created a three‑step workflow:

Step 1: Technical solution – Write a concise description of the architecture and key decisions before touching code.

Step 2: Vertical ticket breakdown – Split the solution into dense technical tickets containing architecture reasoning, edge cases, and context so an Agent can execute them.

Step 3: Claude Code as executor – Submit each ticket to Claude Code with the technical solution as background; a narrow scope yields better Agent performance.

These steps are simple but become problematic when trying to process many tickets sequentially because git only allows one branch per directory.

Bottleneck: One Ticket at a Time

Git’s limitation forces a serial workflow, leading to workarounds such as multiple clones, stash + manual checkout, or third‑party tools, each with drawbacks like disk waste, fragility, or added complexity.

Solution: git worktree

git worktree, introduced in July 2015, lets multiple working directories share a single .git repository. Each directory can be on its own branch, avoiding duplication and enabling parallel work.

Basic Process

cd ~/projects/my-app
# From the epic branch, create a worktree for a parallel ticket
git worktree add -b feature/dashboard-filters ../my-app-filters feature/dashboard

cd ../my-app-filters
# Work on the ticket
git add .
git commit -m "feat: add date range filter to dashboard"
git push -u origin feature/dashboard-filters

# Return to main worktree
cd ../my-app
# Once the ticket is merged
git worktree remove ../my-app-filters

Each worktree can be based on any branch (e.g., feature/dashboard, main), and merges remain clean unless the same files are touched.

Why It Matters for Multi‑Agent Setups

Each Agent gets its own isolated worktree, eliminating interference and shared state. Benefits include:

True parallelism: multiple terminals, multiple Agents, each focused on a single task.

Independent testing: each feature can be run and verified before any merge.

Clearer PRs: narrow scopes make reviews more readable.

Beyond Basics: Orchestrating a Full Architecture

In a real product like Lago (React front‑end, Rails API, database, Redis, etc.), worktrees become full environments with dedicated ports and service connections. The author built a bash script called lago-worktree to automate this orchestration.

lago-worktree Script

The script creates a worktree per ticket, assigns ports, and isolates environments. Examples:

lago-worktree create feat-01
# Front‑end available at http://localhost:3001
# API shared on :3000

For tickets involving both front‑end and API:

lago-worktree create feat-02 --from-front=feat/ui --from-api=feat/endpoint
# Front‑end at http://localhost:3002
# Dedicated API at http://localhost:4001

Listing running instances:

lago-worktree ps
# Name      Front‑end                API                     Status
# feat-01   http://localhost:3001 [main]   Shared                 Running
# feat-02   http://localhost:3002 [feat/ui] http://localhost:4001 [feat/...] Running

Cleaning up after completion:

lago-worktree destroy feat-02
# Removes both front‑end and API worktree directories

All worktrees share the same database, Redis, and event stream, keeping resource usage low while providing isolated testing environments.

Parallel Work Is Effective—Human Bottleneck Remains

With multiple independent architecture instances running in parallel, the limiting factor becomes the human overseeing the Agents. As Agents generate code faster than reviews can keep up, quality depends heavily on the clarity of tickets and the overseer’s guidance. The author acknowledges this new challenge and notes that solving it is an open problem.