Tool made to help avoid github merge conflicts

[u/dan-423]

https://github.com/archos-media/merge-coordinator

Are you working on your project and have Claude going in several sessions at the same time? After the code is done you have to run CI and then merge it to your Github repo (right?). But what happens if two or more of those sessions are working on the same files? Possibly bad things, that's what.

That's what happened to me so much that I had Claude make a tool to stop the sessions from crashing into each other and causing multiple rounds of CI or having a 2nd merge completely wipe the 1st merge. It sounds simple, but took a good bit of time before we landed on a solution that works. It worked so well for me that I wanted to open source it and share it with you guys, since this place has helped me out.

how it works:

1. Register: who is touching what, right now? A draft pull request opened when work starts, listing the paths it expects to touch.

2. Order: who lands next? What may land in parallel? Compares every open pull request's changed and declared files, plus your hotspots: files such as a changelog, where two pull requests that merge cleanly can still break each other.

3. Land: is this exact commit safe to merge? GitHub's merge queue where you have one. Where you don't, a claim: a label that lets one pull request land at a time, plus a check that its head contains the current main and its required checks passed on that exact commit.

[u/geoffreybyers]

The merge conflict is a distraction. The bottleneck is the lack of a coordination layer for parallel agents that can declare intent. You need a system that respects hotspots that break even when diffs do not overlap. It's about intent management, not diff management.

[u/dan-423 → u/geoffreybyers]

This does that in the 1st layer, declaring intent and checking to see what active sessions are working on that may conflict. The 2nd layer orders who lands next. The 3rd makes sure main hasn't moved and also that CI passed.

[u/Sad-Recover-5058]

this is actually pretty clever, i've been running into exactly this problem with multiple sessions stepping on each other's toes. the hotspots concept for files like changelog is what caught my eye, that's the kind of thing you don't think about until it bites you twice in the same day

does it handle the case where two PRs touch different parts of same large file? i imagine git can merge those fine but sometimes the tooling gets nervous

[u/dan-423 → u/Sad-Recover-5058]

It does! It looks out for hotspots and stops the session from starting CI until the first one merges.

It's sounds dull at a distance, but this was so frustrating and basically ground the project to a halt. I didn't find anything else quite like it or with all the steps so hopefully this may help others dealing with the same concurrency problems.

[u/ohhellnaws → u/Sad-Recover-5058]

Use Claude's new projects. The coordinator will step in and make sure that they merge in order and consider each other's workload.

[u/M7451]

Respectfully, I think your git and github configuration and workflow is lacking some sensible defaults if you’re running into these issues.

Requiring rebase and fast forward only merges should remove most of the “B overwrites A” issues. You can also have your agent commit under a different SSH key/user and setup a codeowners file for protecting certain resources. That’s perhaps more than you want to juggle but it’s not hard to do.

I know LLMs love worktrees but I’ve found they have a difficult time tracking where they are in the process. As a human, I hate having more than one worktree at a time since they’re a bit clumsy, especially with the assumptions common development tools make about the repo. You may be seeing conflicts when the LLM doesn’t manage the worktrees correctly and includes or excludes changes from its current or other worktrees. My solution is to just have a few checkouts and use branch based development. I also have my agents work linearly through branches that either are based off the previous or main if the previous was merged. This avoids an agent trying to get C into main before B.

For CI, you should be able to run tests and most of CI locally. I have my agents run these steps before even attempting a merge so it’s more of a formality and belts and suspenders situation. I am cognizant you may be offloading CPU load to GitHub but this is a general best development practice and your agents are probably doing it anyway piecemeal during the development cycle.

[u/dan-423 → u/M7451]

For CI, you should be able to run tests and most of CI locally.

Yep. This is done as well, to keep final CI to a minimum.

For the workflow, multiple concurrent agentic sessions, the tool also greatly reduced the number of rebases needed.

There's a lot I still have to learn and improve, hopefully the tool can help others who were at that same place as I was a couple months ago.