How the Parallel Builder Agent System Uses Git Worktrees for Concurrent Component Builds

The parallel builder agent system creates isolated Git worktrees for each component build, allowing multiple agents to compile TypeScript simultaneously while sharing the same underlying repository history.

The ai-website-cloner-template repository implements a sophisticated concurrency architecture that leverages Git worktrees to enable parallel component generation. According to the source code in .opencode/commands/clone-website.md and the repository README, this design allows multiple builder agents to operate on separate branches simultaneously while utilizing the same Git object database, eliminating the performance bottlenecks of sequential builds.

Understanding Git Worktrees in the Parallel Builder Context

Git worktrees allow a single repository to maintain multiple working directories that share the same .git object store. In the parallel builder agent system, each component build gets its own directory-per-branch environment. This means builder agents can freely modify files, install dependencies, and run compilation checks without interfering with the main working tree or other concurrent builds.

The architecture documented in README.md (line 93) describes how the clone-website workflow dispatches builder agents into these isolated worktrees, while the detailed workflow specification in .opencode/commands/clone-website.md (line 379) outlines the specific dispatch mechanism for concurrent processing.

Worktree Creation and Branch Management

When the clone-website workflow identifies a section requiring component generation, it spawns a builder agent and executes a worktree-add operation. The system creates a fresh branch for each component and checks it out into a dedicated directory:

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" });
}

This approach ensures that git worktree add <tmp-dir> <branch-name> creates a private copy of the repository files while the .git directory remains shared with the main repository.

Isolation for Concurrent Component Builds

Because each worktree lives in its own directory, builder agents can perform destructive operations without risk. Agents freely add, modify, or delete files for their assigned component—such as generating React components like src/components/ui/button.tsx or utility files like src/lib/utils.ts—while the main branch and other worktrees remain untouched.

The OpenCode SDK types defined in .opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts (line 18) provide the underlying API definitions that power these worktree manipulation operations.

Build Verification Inside Worktrees

Local TypeScript Compilation Checks

Each builder agent verifies generated code locally before committing changes. The system runs npx tsc --noEmit inside the worktree directory to validate TypeScript compilation without emitting files:

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

Only when this verification passes does the agent proceed to commit operations, ensuring that broken code never reaches the shared repository history.

Commit Operations in Isolated Environments

After successful verification, the builder agent commits the changes to its branch and pushes to origin:

/**
 * 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",
  });
}

Orchestrating Parallel Builds and Merging

The main orchestrator script manages the parallel execution using Promise.all() to coordinate multiple builder agents. After all worktrees complete successfully, the system merges the component branches back into the main branch:

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" });
}

The orchestrator resolves any merge conflicts between worktree branches, then executes a final npm run build on the unified codebase to produce the production-ready website.

Summary

• Git worktrees provide directory-per-branch isolation that enables true parallel execution of builder agents without file system conflicts.
• Branch isolation ensures each component builds in its own environment derived from main, with changes verified via npx tsc --noEmit before commit.
• Shared repository architecture allows worktrees to share Git object storage while maintaining separate working directories, optimizing disk usage.
• Orchestrated merges bring verified component branches back into the main codebase, followed by a final unified build process.
• Source implementation spans README.md, .opencode/commands/clone-website.md, and the OpenCode SDK types in .opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts.

Frequently Asked Questions

How does the parallel builder agent system prevent conflicts between concurrent builds?

The system uses Git worktrees to create physically separate directories for each builder agent. Because each agent operates in its own directory—checked out to a unique branch—file modifications in one worktree cannot collide with operations in another. The underlying Git object store is shared, but the working trees remain independent until the orchestrator merges them.

What command validates TypeScript compilation inside a worktree?

The builder agent executes npx tsc --noEmit inside the worktree directory to verify type safety. This command runs with the worktree path as the current working directory (cwd: worktreePath), ensuring the check uses the component's specific dependencies and configuration before the agent commits changes to the branch.

Where is the parallel build workflow documented in the repository?

The high-level architecture appears in README.md at line 93, while the detailed workflow specification resides in .opencode/commands/clone-website.md at line 379. Additionally, the OpenCode SDK type definitions in .opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts (line 18) define the worktree manipulation API used by the orchestrator.

Why use Git worktrees instead of separate repository clones?

Git worktrees share the same .git object database, significantly reducing disk usage and network overhead compared to independent clones. This architecture allows the parallel builder agent system to spawn dozens of concurrent builds without duplicating the entire repository history, while still providing the isolation necessary for independent file operations and branch management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}