How to Build a Development Environment for Running Coding Agents in Parallel Using Git Worktree

📝 Originally published (in Japanese) at forge.workstyle.tech.

When trying out multiple coding agents (like Claude Code or Codex), you might run into these challenges: "I want to work on different tasks simultaneously in the same repository, but the work interferes with each other," or "I want to compare the results from Agent A and Agent B side by side."

The solution to this is a parallel execution environment using git worktree. In this article, we'll walk through the process from setup to parallel comparison and deployment approval, using a dedicated desktop-type ADE (Agent Development Environment) as an example. Since the focus is on the concept rather than specific tools, you can adapt it to your own environment.

Why git worktree?

git worktree allows you to create multiple working directories from a single repository. Each branch gets its own independent folder, enabling use cases like:

• Assigning Task A to one agent and Task B to another
• Changes are confined to separate directories, preventing file conflicts
• Giving the same problem to multiple agents and comparing their quality side by side using diffs

The key difference from branch switching (git checkout) is that worktree allows for physically separate parallel work.

Prerequisites

Before setting up the environment, ensure you have the following:

• Coding agent CLI (e.g., Claude Code) with authenticated login status
• git and node (runtime used in the project's CI)
• The main ADE application that manages the agents

Agent authentication is typically stored in home directory settings (e.g., ~/.claude), and the ADE automatically references these settings. If you're already logged in via the CLI, no additional login setup is usually required, and you can start using it directly from the GUI.

Setup Process

1. Launch the app and grant initial permissions

On first launch, grant access to the home directory if prompted. If asked to import existing settings, you can skip this step if not needed.

2. Add a repository

Register the repository you'll be working on. It's recommended to start with a small sample repository for practice rather than a production one. Upon adding, the git status is read, and the default branch (usually main) is set as the base ref.

3. Create a worktree (task)

Create a new worktree with a task name. This becomes an independent git worktree from main, providing an isolated workspace for the task. Use descriptive task names like add-readme-section for easier tracking later.

4. Assign an agent

Select the agent to use for each worktree. Authentication automatically references the previously mentioned settings, so if you're logged in, execution is immediate.

5. Provide a prompt and execute

Give a specific instruction like "Add a usage section to the README" and run it.

6. Compare in parallel

This is where the parallel environment shines. Repeat steps 3-4 to create multiple worktrees (e.g., -2, -3) for the same problem, assigning different agents to each. Split the panes to monitor progress simultaneously and compare results side by side.

From Review to Deployment

Review changes in each worktree's diff view. If available, use AI-powered diff evaluation (annotations) for initial screening.

Once satisfied, commit & push. From here, follow the automated pipeline:

1. PR Creation — A pull request is created upon push
2. CI Execution — Tests (e.g., node --test) run automatically
3. Deployment — Keep production deployment as a manual trigger (Run workflow), introducing a human approval gate

The key to safe operation is maintaining the CI and human approval process, even for agent-generated code. Especially with automated generation, don't skip the two-tiered approach of mechanical testing and human review.

Common Pitfalls

PATH Issues

The most common issue is "agent CLI not found." If using version managers (like fnm or nvm) for node or CLIs, they're only added to PATH after initialization in shell profiles (e.g., .zshrc).

If the ADE's shell doesn't load this profile, commands won't be found. If you encounter "command not found," check the shell profile initialization lines.

Authentication Conflicts

When switching between multiple accounts, most implementations guard against duplicate authentication refreshes. Generally, relying on home directory settings is sufficient.

Summary

• Use git worktree for non-interfering parallel execution of multiple coding agents
• Assign the same problem to multiple agents and compare quality side by side using diffs
• Review via diff view; protect production with CI + human approval gate
• The biggest pitfall is PATH: ensure version manager initialization is in shell profiles

In most environments, you'll need to install little new software, and can start parallel agent development by simply connecting existing CLI authentication. Begin by trying the same instruction with 2-3 agents on a practice repository and comparing the results.