Dev.to AI 🤖 Ai 👁 0 📖 8 min read

I Had 4 Days to Tackle a 29-Page Issue Document. Here's How I Ran Parallel AI Agents with Git Worktrees

Software development doesn't always come with comfortable timelines. Recently, I was handed a 29-page requirement document containing 30+ issues, ranging from existing bugs and functional problems to improvements and en

I Had 4 Days to Tackle a 29-Page Issue Document. Here's How I Ran Parallel AI Agents with Git Worktrees

Software development doesn't always come with comfortable timelines.

Recently, I was handed a 29-page requirement document containing 30+ issues, ranging from existing bugs and functional problems to improvements and entirely new features.

Handling everything sequentially with a single AI coding agent wasn't practical. Some tasks required investigating existing implementations, others involved changes across multiple modules, and a few required developing entirely new functionality.

I needed a way to increase development throughput without turning the codebase into a collection of conflicting AI-generated changes.

So, I experimented with running multiple AI coding agents in parallel using Git branches and worktrees.

Across the workflow, I used approximately 10 branches, multiple Git worktrees, and several OpenCode sessions running parallelly. I also experimented with assigning the same feature to two different agents to compare their implementations.

Here's how I approached task distribution, isolated agent environments, branch management, integration, and verification.

This is a practical account of my experience, not a benchmark claiming that more agents automatically mean faster development.

1. The Architecture: OpenCode + Git Worktrees

I used three primary components:

  • OpenCode: To run multiple AI coding sessions.
  • Git branches: To maintain independent development histories.
  • Git worktrees: To provide separate working directories for different branches.

It's important to understand how these components work together.

A Git branch represents an independent line of development. A Git worktree provides a separate working directory associated with a branch. An AI agent performs the actual implementation inside that directory.

Instead of making multiple agents work inside the same project directory, I could give each one its own workspace.

Showing the example branching and procedure of work

Setting up Git worktrees

One advantage of Git worktrees is that you don't need to clone the entire repository multiple times.

You can create separate working directories directly from your existing repository:

git worktree add ../project-task-a -b feature/task-a

git worktree add ../project-task-b -b feature/task-b

git worktree add ../project-task-c -b fix/task-c

Each command creates a new branch and checks it out in a separate directory.

You can verify your worktrees using:

git worktree list

Now, launch separate OpenCode sessions from each directory:

cd ../project-task-a
opencode

Repeat this for the other worktrees.

Each session now operates on its own working directory, branch, and uncommitted changes.

One important distinction: Running multiple OpenCode sessions doesn't automatically isolate them. The isolation comes from explicitly assigning each session to a separate Git worktree.

2. Task Decomposition: Not Everything Can Run in Parallel

Creating multiple worktrees is relatively easy. Deciding what should run inside them is the more important engineering decision.

Before assigning tasks, I considered three things:

Functional independence: Can the task be implemented without waiting for another task?

Code ownership: Which modules, directories, or files will the agent modify? Are multiple agents likely to touch the same files?

Dependencies: Does the implementation depend on another feature, API contract, database schema, or shared component?

For example, implementing a new backend API and building an unrelated frontend component can happen concurrently.

However, if a frontend feature depends on an API that hasn't been defined yet, both implementations need coordination.

I also treated agent instructions as implementation contracts rather than simple prompts.

Each task brief needed to communicate the actual problem, expected behaviour, relevant modules, implementation boundaries, existing functionality that must remain unaffected, dependencies, and testing expectations.

A vague instruction such as "fix the dashboard" leaves too much room for interpretation. A task with defined expected behaviour and acceptance criteria gives the agent a much clearer direction.

The objective wasn't to maximize the number of running agents. It was to maximize independent execution while minimizing overlapping changes.

3. Two Agents, One Issue: Comparing Different Approaches

One of the more interesting experiments involved assigning the same issue to two different AI coding agents.

I had two approaches in mind, so instead of choosing one immediately, I assigned each approach to a separate agent.

Both received the same requirement but worked independently in separate Git worktrees, exploring their respective approaches and producing different implementations.

I deliberately didn't share one agent's implementation with the other.

Why?

I wanted to see how differently the same problem could be approached without one implementation influencing the other.

Once both implementations were ready, I compared them based on:

  • Correctness: Did the implementation satisfy the requirement, including edge cases?
  • Architectural compatibility: Did it fit the existing application structure?
  • Maintainability: Was the code understandable without unnecessary abstractions?
  • Testing: Were there meaningful tests covering the expected behaviour?
  • Integration complexity: How much additional work was required to introduce it into the existing codebase?

Rather than automatically choosing one agent's output, I reviewed both solutions and selected the approach better suited to the existing application.

This gave me the opportunity to explore alternative solutions before committing to one implementation.

The experiment looked like this:

flowchart TD
    A["Same Feature Requirement"] --> B["Shared Task Brief"]
    B --> C["Agent A"]
    B --> D["Agent B"]
    C --> E["Implementation A"]
    D --> F["Implementation B"]
    E --> G["Comparative Review"]
    F --> G
    G --> H["Tests and Code Review"]
    H --> I["Select Implementation"]
    I --> J["Integration"]

However, this isn't something I'd recommend for every issue. Running two agents on the same task increases implementation and review effort.

It's more useful for complex features or architectural decisions where comparing alternatives is worth the additional cost.

4. Branch Management: Stacking, Cherry-Picking and Integration

In an ideal parallel development workflow, every task would have its own branch created directly from master.

My actual Git history was more complicated.

Only two lines of work started directly from master. Several other branches were created on top of existing feature branches.

This resulted in a stacked branch structure.

For example:

master
 |
 +--- feature/base
       |
       +--- feature/extension-a
       |      |
       |      +--- feature/extension-b
       |
       +--- fix/integration

Stacked branches are useful when one implementation depends on another.

Instead of duplicating unfinished changes or waiting for everything to merge into master, a dependent branch can build on an existing implementation.

However, this also introduces dependencies between branches. If an upstream branch changes, dependent branches may need to be rebased or updated.

I also used git cherry-pick to selectively move commits between development branches:

git cherry-pick <commit-hash>

Rather than merging every branch wholesale, I could select the commits that were actually useful and bring them into my integration branch.

This gave me more control over what entered the final codebase.

Out of all commits I authored during this period, around six were set aside or replaced. One documentation commit was dropped completely.

Parallel development doesn't mean accepting every agent's output. An implementation is a candidate, not an automatic contribution to the final codebase.

5. Integration: Where Things Get Interesting

Worktrees solve the problem of multiple agents modifying the same local working directory. They don't eliminate integration conflicts.

Two agents can independently modify different worktrees and still produce incompatible changes.

For example, two features might modify the same API service, shared TypeScript interface, database model, application state, or common UI component.

Their changes won't overwrite each other's local files, but they may conflict when combined.

During integration, I encountered three merges that required conflict resolution. The largest conflict involved 17 files, because two competing implementations had modified several of the same areas.

I used a combination of Git commands to understand and manage these changes.

Inspect changes between branches:

git diff main...feature/task-a

Understand the commit history:

git log --oneline --graph --all

Check the working tree:

git status

Integrate a branch:

git merge feature/task-a

When conflicts occurred, I resolved them by understanding what each implementation was trying to achieve rather than blindly accepting one side.

Git can identify conflicting changes, but it cannot determine which implementation is architecturally correct.

That decision still requires engineering judgment.

6. Verification: Passing Individual Tests Isn't Enough

One of the biggest mistakes in multi-agent development is assuming that if every agent reports successful implementation, the application is ready.

An agent can successfully implement and test its own changes without guaranteeing that the combined application works.

After integration, I still needed follow-up commits to fix TypeScript errors and update test snapshots.

These fixes were completed within approximately half an hour of merging.

The complete integration process, from creating the integration branch to pushing it, took roughly 40 minutes.

After the fixes, the project's test run showed:

Result Count
Passing tests ~4,000
Existing failures 28

The 28 failures were already present before this work.

This is why having a known testing baseline matters. Without it, pre-existing failures can easily be mistaken for regressions introduced by new changes.

My verification process involved reviewing the integrated Git diff, resolving implementation and type errors, checking test snapshots, running the project's test suite, and distinguishing existing failures from newly introduced issues.

Agent-level verification and system-level verification are two different things.

An agent can verify its assigned task. The developer still needs to verify the application as a whole.

7. What I'd Do Differently Next Time

The workflow worked, but there are several things I'd approach differently in the next iteration.

Establish file ownership earlier. Before launching agents, I'd define which modules and files each task is expected to modify. This would reduce overlapping changes.

Define shared interfaces before implementation. For tasks involving frontend, backend, and database changes, I'd establish API contracts and shared types before parallel execution.

Integrate incrementally. Waiting until multiple implementations are complete increases integration complexity. I'd merge smaller changes more frequently and run regression tests after each meaningful integration.

Maintain a central task registry. I'd maintain a single place containing task descriptions, branch names, worktree paths, dependencies, ownership, status, and verification results.

Use competing implementations selectively. Running two agents on the same issue was useful, but it also increased review and integration work. I'd reserve it for high-impact features.

Conclusion

Four days, a 29-page requirement document pushed me to experiment with a different approach to AI-assisted development.

Using OpenCode sessions alongside Git branches and worktrees gave me a way to distribute implementation across independent environments while retaining control over integration.

The two-agent experiment also showed me that parallel coding can be useful beyond implementation speed. It can help explore alternative solutions before committing to an architectural direction.

But parallel execution doesn't eliminate engineering responsibility. It shifts where that responsibility sits.

The agents can investigate, implement, and test. Someone still needs to decide how the work fits together, which implementation is worth keeping, and whether the final application actually works.

If you're experimenting with multi-agent coding, I'd suggest starting with two or three independent tasks, giving each a separate worktree, defining clear boundaries, and integrating changes incrementally.

Scale the number of agents only when your ability to coordinate and verify their output can keep up.

The next evolution of AI-assisted development isn't necessarily one agent that writes more code. It's a coordinated system of agents that can work independently without losing control of the engineering process.

This article documents one practical development experience, not a controlled performance benchmark. The numbers reflect my project and workflow and shouldn't be interpreted as guaranteed productivity improvements.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.