Six Agents, One Repo: The Git Workflow That Keeps It From Falling Apart

Blog post #22

Six colored Git branches diverging from and merging back into a protected main branch.

A few months ago, I was running one Claude Code agent at a time.

One task. One thread. One conversation. I’d finish it, merge, and start the next one. Simple. Safe. Predictable.

Then I started running two in parallel. Then three.

Today I regularly run up to six simultaneous Claude Code agents on the same project — each working on different parts of the codebase, each with its own context, none of them aware the others exist.

That should be chaos. It’s not. Here’s why.

The Problem With Parallel Agents and No Rules

Imagine two agents both working on the same project. Agent A is refactoring the database layer. Agent B is adding a new API route that touches the same schema.

Without rules:

  • Both agents work on main
  • Agent A pushes first
  • Agent B pulls, gets conflicts, or worse — pushes over Agent A’s changes without noticing
  • You end up with a broken main and an unclear git history

The more agents you add, the worse this compounds. Six agents on main is six simultaneous bets that no two of them will ever touch the same file. That bet loses constantly.

The Fix: One Branch Per Agent, No Exceptions

The rule I built into my global Claude instructions is simple:

Every new task starts on a feature branch. Every agent gets its own branch. Nobody touches main directly.

feat/short-description

That’s it. Each agent runs git checkout -b feat/whatever before it does anything. It commits and pushes to that branch throughout the task. When it’s done, it creates a PR with gh pr create and merges.

Main is protected. You can’t push to it directly — it requires a PR. That’s the hard constraint that makes the soft constraint (branch naming convention) actually hold.

Why This Works for a Solo Developer

Most branch-based workflows exist to enable code review. You create a PR, someone reviews it, it gets merged. The whole point is the human checkpoint.

I don’t have that. I’m a solo developer. There’s no reviewer. I merge my own PRs.

But the branch workflow still earns its cost for a different reason: isolation.

When Agent A is on feat/db-refactor and Agent B is on feat/new-api-route, they literally cannot conflict in git. They’re working in separate namespaces. If they both touch the same file, the conflict surfaces at merge time — when I’m looking at both PRs and can decide which change takes priority.

The conflict doesn’t disappear. But it moves from silent data corruption to a diff I can actually read.

The Merge Strategy

Because I merge quickly (solo dev, no multi-day reviews), the typical flow looks like this:

  1. Agent starts task → creates feat/ branch
  2. Agent commits continuously as it works
  3. Task complete → gh pr create (title + summary auto-generated)
  4. I scan the diff, merge, done

The gh CLI does the heavy lifting. I don’t open GitHub in a browser unless something looks off. The whole merge cycle takes maybe 30 seconds for most tasks.

For larger changes or anything that touches shared infrastructure, I’ll read the PR more carefully. But the branch strategy means I’m reviewing a clean, bounded diff — not trying to reconstruct what three agents did to main over the last hour.

What the Instructions Actually Say

My global CLAUDE.md file has a Git section. Every Claude Code agent I run reads it at the start of every conversation:

- Start every new task on a feature branch: git checkout -b feat/short-description
- Commit and push to the branch continuously, without asking
- When done: create PR with gh pr create and merge immediately (no review required, solo dev)
- NEVER push directly to master — master is protected and requires a PR
- If running multiple Claude threads in parallel: each thread gets its own branch

That last line is the key one. I wrote it specifically because I started running parallel agents and needed the rule to be explicit.

Claude Code follows it. Every time. That’s the contract.

Scaling From 2 to 6

Going from 1–2 agents to 6 didn’t require any new tooling. The branch workflow scaled linearly. More agents just means more branches, more PRs, more merges.

The things I watch for:

Migration files. If two agents both create a database migration, I’ll have two 004_something.sql files. I catch this at PR time and renumber. It’s annoying but rare and obvious.

Shared types and interfaces. If two agents modify the same TypeScript type, there will be a conflict. Again — visible at merge, not silent.

The order of merges matters. If Agent A’s PR changes a file that Agent B’s PR also changed, I merge the simpler one first and let Agent B’s PR show the conflict cleanly.

None of these are catastrophic. They’re just merge decisions, and they happen in a controlled context instead of a tangled main branch.

The Counter-Question Habit

One thing I’ve started doing: when Claude Code asks me to do something — “should I proceed?”, “do you want me to run X?” — I push back with a counter-question before answering.

Not to be difficult. But because the agent often knows enough to make the call itself, and the question is a prompt for me to rubber-stamp something I haven’t fully thought about.

Asking “what would happen if you did proceed?” or “why are you unsure?” usually produces a better answer than just saying yes. Sometimes the agent realizes the question was unnecessary and just does the right thing. Sometimes the uncertainty was real and worth surfacing.

This is a small habit but it’s made a noticeable difference in the quality of what gets built.

Where This Goes Next

Six parallel agents on one project is near the ceiling of what I can coherently track in my head at once. Not because of git — that part scales fine — but because I still need to understand what each agent is doing well enough to review the diff.

The next problem isn’t tooling. It’s attention.

That’s the one bottleneck that doesn’t have a CLAUDE.md fix.

— Stefan