How I Run Multiple Coding Agents in Parallel Using Git Worktrees

Mahmood Khordoo — Thu, 04 Jun 2026 18:21:30 +0000

A practical local workflow for running Claude, Codex, and Gemini side by side without breaking your repo.

When developers hear “multi-agent coding,” they often assume it means something complex.

With all the talk about supervisor agents, agent swarms, agent teams, and subagents, it can feel like you need a heavy setup before you can even start. In reality, for day-to-day local development, you can keep it much simpler. You do not need a complex system just to run multiple coding agents in parallel.

The foundation of practical multi-agent coding is isolation.

If you want to run multiple coding agents concurrently without them destroying your codebase, the architecture relies on one golden rule:

One task = One branch = One Git worktree = One terminal = One agent session.

There is absolutely a time and a place for advanced and complex setups. But you do not need them to see massive productivity gains today. Think of the method below as your practical baseline. It is designed to get you started immediately using tools you already know and have installed.

It keeps you fully in control without overwhelming you. Once you master this foundation, you can always layer on more advanced automation later.

Here is exactly how to set up this straightforward workflow, safely manage multiple agents in parallel, and shift your role from writing every line of code to acting as the Integration Manager.

Step 1: Fix the Single-Folder Bottleneck with Git Worktrees

The fastest way to ruin a multi-agent workflow is to run them in the same working directory.

If Agent A is refactoring a file and Agent B is trying to write tests for it, they will overwrite each other. If you switch branches to check on one agent’s progress, the files change on disk, completely breaking the context for the agent running in the background.

A quick note on Claude Code's newest native features: Anthropic recently added an Agents Panel (claude agents) and a native --worktree flag to their CLI. This proves how critical isolation is! However, relying solely on Claude's native commands locks you into their ecosystem and often buries your worktrees in hidden .claude directories. The manual setup below is vastly superior because it is 100% tool-agnostic (allowing you to mix Claude, Gemini, and Codex), and it gives you complete visual control over your folders inside VS Code.

To solve this, we use a deeply under-appreciated Git feature: git worktree

A Git worktree allows you to check out multiple branches from the same repository into completely separate folders on your hard drive, simultaneously.

For example, let’s say your main project is rag-app and you are currently inside that directory in your terminal. You can provision parallel workspaces using the commands below.

(Pro-tip: Notice the ../ in the paths. This is crucial. It ensures the new worktrees are created side-by-side with your main folder, rather than awkwardly nesting them inside your current Git repository.)

git worktree add -b ai/retrieval-fix ../rag-retrieval-fix main
git worktree add -b ai/eval-tests ../rag-eval-tests main
git worktree add -b ai/review ../rag-review main

Now, if you look at your file system, you have this perfectly clean, parallel structure:

The core mental model of multi-agent coding: Your main workspace stays completely clean (rag-app) , while each agent gets its own physical folder, branch, and dedicated terminal.

Sitting right next to your main rag-app folder, you now have completely distinct, isolated directories:

rag-app (Your clean, protected main checkout)
rag-retrieval-fix(Worktree for Agent 1)
rag-eval-tests (Worktree for Agent 2)
rag-review (Worktree for Agent 3)

Because each directory is connected to the exact same local Git repository but rests on a different branch, your agents now have isolated sandboxes. They can read, write, and run tests concurrently without ever stepping on each other’s toes.

Running git worktree list verifies that your agents now have completely isolated workspaces, all tied to the same local repository but residing on different branches.

Step 2: Build Your Control Room in VS Code

Once you have multiple isolated environments, the next challenge is visibility. You need a way to monitor four different agents without drowning in a sea of open windows.

The solution is a VSCode Multi-Root Workspace.

Open your main worktree, and then explicitly add the parallel worktrees into a single, unified VS Code window:

Open your main project in VScode :

code ~/projects/rag-app

Then add the other worktrees into the same VS Code window:

code --add ~/projects/rag-retrieval-fix
code --add ~/projects/rag-eval-tests
code --add ~/projects/rag-review

Save this layout as a Workspace. VS Code transforms into a centralized dashboard for your AI team.

The Explorer pane displays all worktrees. The Source Control panel cleanly separates the diffs happening in each folder. Paired with an extension like GitLens, it becomes trivial to monitor branches, compare diffs, and audit exactly what each agent is writing in real time.

The VS Code Explorer pane displaying your Multi-Root Workspace. Each folder represents a completely isolated Git worktree ready for a different agent task.

The Source Control panel cleanly separates uncommitted changes across all active worktrees. This allows you to monitor diffs and review agent outputs from one centralized dashboard.

Step 3: Enforce Strict Terminal Discipline

To make this system work, you must adopt strict terminal discipline.

VS Code does not automatically change your integrated terminal’s directory when you click on a file in a different worktree. If you are looking at rag-eval-tests but your terminal is secretly still in rag-app, firing off an agent will result in code being written to the wrong branch.

The Rule: Do not reuse a single terminal and manually cd between worktrees.

Instead, proactively provision a dedicated terminal tab for each worktree and rename them in VS Code.

Once a terminal is open in a specific folder, never use the cd command to leave it. If you need to run commands in a different worktree, simply click over to its matching terminal tab

If you are ever in doubt before executing an agent, run a quick sanity check:

pwd
git branch --show-current

This single habit prevents 99% of multi-agent execution errors.

Pro-Tip: Automate Your Terminal Organization
To make this workflow visually effortless, you can tell VS Code to automatically name your terminal tabs based on their worktree folder.

Add these two lines to your VS Code settings.json:

"terminal.integrated.tabs.title": "${workspaceFolderName}",
"terminal.integrated.tabs.description": "${cwdFolder}"

Ensure you reload your workspace or simply close and reopen VS Code for it to take effect.

How to open terminals correctly:
Because VS Code is tricky, how you open the terminal matters.

Do not just click the dropdown arrow (⌄) and select “New Terminal” (this will default to wherever your currently active file is located).
Instead, click directly on the + icon in the terminal panel. Because you are in a Multi-Root Workspace, VS Code will explicitly ask you which folder you want to open the terminal in. Select your specific worktree.

The Benefit: By doing this, your terminal session automatically opens in the correct physical folder and is locked to the correct Git branch. You never have to manually cd between directories, which eliminates the risk of running an agent in the wrong place.

Once opened, right-click the terminal tab to change its icon and color. This makes managing multiple agents incredibly visual.

Here is the exact layout I use:

By using the ‘+’ button and customizing your tabs, each agent gets a dedicated, color-coded terminal automatically locked to the correct Git branch and folder.

If you want to monitor an agent’s code execution while it writes, you can also split the terminal vertically inside that specific worktree’s tab. This keeps the agent’s CLI tool on one side and the server or execution output on the other.

The massive benefit here is that each session has a dedicated runtime and agent paired together. As you click and switch between your different worktree tabs, the correct agent and its running code stay perfectly synced in one view.

Splitting the terminal inside a worktree tab pairs the agent (like Claude Code) with its execution environment. Switching tabs instantly brings up the correct agent and its corresponding server or test logs

The Multi-Model Advantage

Because every terminal tab is completely isolated, you are not locked into a single AI tool or model.

You can run Claude Code in your testing worktree and Codex CLI in your implementation worktree simultaneously.

You can even run multiple instances of the same tool using different model profiles. For example, you can use a fast, cheap Codex profile in one tab and a premium, heavy-lifting Codex profile in another. This lets you pick the exact right tool for each specific job.

Step 4: Strategic Delegation

With the infrastructure in place, the actual execution becomes highly systematic.

How you delegate depends entirely on your current goal. If you are stuck on a complex architectural problem, giving multiple agents the exact same prompt is actually a great strategy. It allows you to see the problem from different angles, compare alternative solutions, and have one agent review another’s code.

However, while that is highly useful for brainstorming and quick prototypes, having three agents write the exact same feature does not actually speed up your delivery time.

To maximize true engineering productivity, you need to split the workload functionally. By assigning independent tasks to different worktrees, you can move multiple pieces of the project forward at the exact same time.

For example:

Agent 1 (Implementation): Modifies the core logic in Worktree A.
Agent 2 (Testing): Writes unit and integration tests based on the proposed specs in Worktree B.
Agent 3 (Review): Audits the codebase for edge cases or security flaws in Worktree C.

Because these agents are working independently, your prompts must be highly bounded to the scope of the tasks. Vague prompts lead to bloated diffs.

Step 5: Optimize Your Model Economics

Running four parallel agents can burn through API credits quickly if every terminal is hooked up to GPT-5.5 or Claude Opus 4.8

An effective multi-agent workflow requires resource management. Allocate cheaper, faster models (like Gemini Flash, Claude Haiku, or localized models) for routine tasks, and reserve the expensive models for heavy lifting.

Tier 1 (Cheap/Fast): Boilerplate, test generation, documentation, simple refactors.
Tier 2 (Premium): Architecture decisions, complex implementations, final code reviews.

If you use a CLI tool like Codex, you can configure profiles to make switching seamless:

For example, here is how you can set up a custom profile using OpenRouter. First, add the provider block to your main Codex configuration file. ( ~/.codex/config.toml )

Defining OpenRouter as a model provider in Codex. Make sure to export your OPENROUTER_API_KEY in your shell configuration (e.g., ~/.zshrc).

Next, you can define custom profiles for specific models by creating a new file named ~/.codex/{profile-name}.config.toml

For example, here is how you would configure a heavy-lifting profile for DeepSeek Pro ( ~/.codex/ds-pro.config.toml ):

Defining a custom Codex profile specifically for DeepSeek Pro via OpenRouter.

Finally, you can spin up the exact model you need inside each worktree’s dedicated terminal:

codex --profile tier-1-fast
codex --profile tier-2-smart
codex --profile ds-pro

The Paradigm Shift: You Are Now the Integration Manager

Multi-agent coding doesn’t automate the software engineer away; it elevates them.

By utilizing Git Worktrees, Multi-Root Workspaces, and bounded prompting, you shift your daily role from typing syntax to acting as a Tech Lead and Integration Manager.

Your new development loop is highly leveraged:

Write clear, bounded task specifications.
Delegate tasks to isolated worktrees.
Let agents compile candidate diffs concurrently.
Review the outputs in your unified dashboard.
Merge only the code that meets your standards into the main branch.

The main branch stays pristine. The worktrees safely absorb the chaos of iteration.

This is not magic. It is just solid local environment management adapted for modern AI workflows. Set up the infrastructure correctly, and you can comfortably manage a team of AI agents right from your laptop.

Configure Claude Code with AWS Bedrock in 30 Seconds (Python)

Mahmood Khordoo — Tue, 30 Sep 2025 21:12:15 +0000

The Problem: AWS Configuration is tedious

If you’ve tried using the new Claude Code extension with AWS Bedrock, you’ve probably hit the same wall I did.

The extension is amazing, but the setup? It’s a friction-heavy process. You have to:

Log into the AWS Console.
Navigate IAM roles and permissions.
Deal with config and credentials files manually.
Debug vague "Access Denied" errors when it doesn't work.

I just wanted to code with Claude, not spend 20 minutes acting as a SysAdmin.

The Solution: Automating the boring stuff

I realized this process could be scripted. So, I built clauth, a lightweight, open-source Python CLI that automates the handshake between your local environment and AWS Bedrock.

It turns a 15-minute manual setup into a single command.

How to use it

You can install it directly from PyPI.

Step 1: Install

pip install clauth

Step 2: Run the configuration
Run the command in your terminal. It will guide you through the authentication process automatically.

# Make sure to run this in your terminal
clauth

What it does under the hood

For the curious developers, here is what the library handles for you:

Profile Management: Automatically updates your ~/.aws/credentials without breaking existing profiles.
SSO Integration: Handles the browser-based login flow if you are using AWS SSO.
Bedrock Handshake: Verifies that your session actually has access to the Bedrock models before you try to use them in your IDE.

Why Open Source?

I built this to scratch my own itch, but I packaged it up because I know how frustrating AWS IAM can be for developers who just want to use GenAI tools.

The project is fully open source. If you have feature requests or run into edge cases, feel free to open an issue or PR!

PyPI: https://pypi.org/project/clauth/
GitHub: [INSERT YOUR GITHUB LINK HERE]

Happy coding! 🚀

Built by an Engineer who got tired of manually setting environment variables 😉

DEV Community: Mahmood Khordoo