# How the Parallel Build Phase Uses Git Worktree Agents for Concurrent Component Builds

> Learn how the Parallel Build phase uses Git worktree agents for concurrent component builds. Discover isolated builders executing in separate directories without conflicts.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: internals
- Published: 2026-07-04

---

**The Parallel Build phase leverages Git worktrees to spawn isolated builder agents that generate components concurrently in separate directories while sharing the underlying repository data, enabling parallel execution without file conflicts.**

The **ai-website-cloner-template** repository implements a sophisticated parallel builder pattern that utilizes Git worktrees to achieve concurrent component generation. When the `clone-website` workflow processes multiple UI components simultaneously, it creates temporary worktrees that provide each builder agent with an isolated working environment. This architectural decision, documented in the repository's README and workflow specifications, allows the system to build multiple components in parallel while maintaining a single source of truth in the repository's object database.

## Git Worktree Architecture for Parallel Execution

The parallel builder system relies on Git worktrees to create lightweight, isolated environments for each component build. According to the implementation in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) (line 379), the orchestrator creates these environments dynamically during the cloning workflow.

### Worktree Creation and Branch Isolation

When the workflow identifies a component requiring generation, it spawns a builder agent and executes a **worktree-add** operation. The system runs `git worktree add <tmp-dir> <branch-name>` to create a new working directory linked to a dedicated branch for that component. As defined in the OpenCode SDK types (`.opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts` line 18), this operation creates a separate working tree while sharing the same `.git` object database, minimizing disk overhead while maximizing isolation.

The branch naming convention follows the pattern `builder/<component-name>`, ensuring that each component's generated code remains isolated in version control until the final merge.

### Concurrent Build Isolation

Because each worktree lives in its own directory, builder agents can freely modify files without interfering with other concurrent builds. The repository's README (line 93) documents this design, noting that builders can add, delete, or overwrite files within their assigned worktree while the main working directory and other worktrees remain untouched. This isolation prevents the race conditions that would occur if multiple agents attempted to write to the same directory simultaneously.

## Build Verification and Integration Workflow

The parallel build process implements a strict verification gate before integrating component code into the main branch.

### TypeScript Verification in Worktrees

Each builder agent validates its generated code locally before requesting a merge. The verification executes `npx tsc --noEmit` within the worktree directory to perform type checking without emitting compiled files. This check ensures that components like those found in [`src/components/ui/button.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/ui/button.tsx) and utilities in [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) meet the project's TypeScript standards before they are committed to their respective branches.

### Orchestration and Cleanup

After all builder agents complete their verification steps, the orchestrator manages the integration process:

1. **Merge execution** – The orchestrator merges each worktree branch back into the main branch, resolving any conflicts that arise from concurrent modifications.
2. **Final build** – Once all branches are merged, the system runs `npm run build` on the unified codebase to produce the final application bundle.
3. **Worktree removal** – The temporary worktrees are cleaned up using `git worktree remove <tmp-dir>` to free disk space and maintain repository hygiene.

## Implementation Example

The following utilities demonstrate the worktree management pattern used by the parallel builder agents:

```typescript
import { execSync } from "child_process";

/**
 * Create a temporary worktree for a component.
 * @param worktreePath – absolute path where the worktree will be placed
 * @param branchName – name of the branch that will host the component code
 */
export function createComponentWorktree(worktreePath: string, branchName: string) {
  // Ensure the branch exists (or create it from main)
  execSync(`git checkout -b ${branchName} main`, { stdio: "inherit" });
  // Add the worktree
  execSync(`git worktree add ${worktreePath} ${branchName}`, { stdio: "inherit" });
}

/**
 * Run the TypeScript compiler in the worktree to verify the build.
 */
export function verifyWorktree(worktreePath: string) {
  execSync(`npx tsc --noEmit`, { cwd: worktreePath, stdio: "inherit" });
}

/**
 * After successful verification, commit and push the worktree branch.
 */
export function finalizeWorktree(branchName: string) {
  execSync(`git add . && git commit -m "Component build" && git push origin ${branchName}`, {
    stdio: "inherit",
  });
}

```

The orchestration layer coordinates these operations across multiple components:

```typescript
import { createComponentWorktree, verifyWorktree, finalizeWorktree } from "./worktree-utils";
import { execSync } from "child_process";

async function parallelComponentBuild(components: string[]) {
  const promises = components.map(async (comp, i) => {
    const worktreeDir = `/tmp/worktree-${comp}-${i}`;
    const branch = `builder/${comp}`;
    createComponentWorktree(worktreeDir, branch);
    // The actual component generation happens here (omitted for brevity)
    // ...
    verifyWorktree(worktreeDir);
    finalizeWorktree(branch);
    // Cleanup the temporary worktree after merging
    execSync(`git worktree remove ${worktreeDir}`, { stdio: "inherit" });
  });

  await Promise.all(promises);
  // After all worktrees are merged, run the final build
  execSync(`npm run build`, { stdio: "inherit" });
}

```

## Key Implementation Files

The parallel build system is implemented across several key files in the repository:

- **[`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md)** – Contains the high-level description of the parallel build architecture (line 93) and explains how builder agents utilize worktrees for concurrent execution.
- **[`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md)** – Documents the full workflow specification showing how the orchestrator dispatches builder agents in worktrees (line 379).
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** – Provides the `cn` utility function used by generated components, representing the type of code produced by builder agents.
- **[`src/components/ui/button.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/ui/button.tsx)** – Example component demonstrating the output structure expected from the parallel build process.
- **`.opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts`** – Defines the TypeScript interfaces and worktree API used by the orchestrator to manage parallel builds.

## Summary

- **Git worktrees** provide the isolation mechanism for parallel builder agents, allowing concurrent component builds while sharing repository history.
- **Branch-per-component** strategy ensures that each builder agent's changes remain isolated until the verification phase completes.
- **TypeScript verification** (`npx tsc --noEmit`) runs independently within each worktree before any code merges into the main branch.
- **Orchestrator pattern** manages the lifecycle of worktrees, from creation through verification to final cleanup using `git worktree remove`.
- **Implementation** spans the workflow documentation in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) and the SDK types that define the worktree API.

## Frequently Asked Questions

### What is the purpose of using Git worktrees in the Parallel Build phase?

Git worktrees allow the Parallel Build phase to create isolated working directories for each component without the overhead of cloning the entire repository. Because worktrees share the same `.git` object database while maintaining separate working directories, multiple builder agents can run simultaneously on the same machine without file conflicts, enabling true parallel execution.

### How does the orchestrator handle conflicts between parallel worktrees?

The orchestrator merges each worktree branch back into the main branch only after all builder agents complete their verification steps. If conflicts occur during these merges—such as when two components modify shared dependencies—the orchestrator resolves them sequentially before running the final `npm run build` on the unified codebase.

### What verification step ensures code quality before merging worktree branches?

Each builder agent executes `npx tsc --noEmit` within its worktree directory to perform static type checking. This verification ensures that generated components, such as those matching the patterns in [`src/components/ui/button.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/ui/button.tsx), compile without errors before the worktree branch is eligible for merging into the main branch.

### How are temporary worktrees cleaned up after the build completes?

After a builder agent finishes its work and the orchestrator merges the component branch, the system removes the temporary worktree using `git worktree remove <tmp-dir>`. This command deletes the working directory while preserving the branch history in the shared `.git` database, preventing disk space accumulation during large-scale cloning operations.