Based on your Merge Magic draft , here’s a cleaner CEO-style Markdown version:

# Merge Magic: Resolving the Merge Conflicts That Shouldn’t Need a Human

I built **Merge Magic** because I got tired of resolving the same merge-conflict pattern over and over again.

Same conflict shape.  
Same “keep both” outcome.  
Same wasted time every time I rebased onto `main`.

At first, it was a small utility to remove that friction. Over a few weeks, it became something I now use daily.

Merge Magic automatically resolves merge conflicts that are clearly additive, while surfacing the ones that actually require human judgment.

It is free, bring-your-own-AI, and it never auto-commits.

You stay in control.

---

## What Merge Magic Does

Merge Magic is designed around a simple idea:

> Most merge conflicts are not real disagreements.  
> They are just two useful changes landing in the same place.

For example:

```js
<<<<<<< HEAD
export function getUser(id) {
  console.log('[users] fetch', id);
  return db.users.findById(id);
}
=======
export function getUser(id) {
  if (!id) throw new Error('id required');
  return db.users.findById(id);
}
>>>>>>> feature/validation

One branch added logging.
Another added validation.

The correct resolution is obvious: keep both.

A developer can resolve this in 30 seconds. But multiplied across every rebase, every PR, and every team member, those 30 seconds become a tax.

Merge Magic removes that tax where it can — and refuses to guess where it should not.

How It Works

Merge Magic resolves conflicts in three layers.

1. Mechanical Pre-Pass

Some conflicts can be resolved safely from text alone.

Examples include:

• Identical edits on both sides
• One-sided edits where the other side matches the base
• Clearly additive changes in different parts of the same region

These require no AI call.

They are resolved instantly because the answer is structurally obvious.

2. AI-Assisted Resolution

For conflicts that need more context, Merge Magic dispatches the conflict to whichever AI tool you already use.

Supported backends include:

• VS Code language model API
• Copilot
• Claude Code CLI
• Ollama
• Anthropic
• OpenAI
• Gemini

There is no forced subscription layer.

You bring the model. Merge Magic brings the workflow.

3. Verification Floor

Every auto-resolved file is checked against build diagnostics.

Merge Magic captures the baseline error set first, then checks the merged result.

If the resolution introduces new errors, it reverts the file back to conflict markers and shows the actual diagnostic.

Pre-existing errors do not cause false failures.

This is the safety floor.

The Line I Refused to Cross

The most important design decision was not what Merge Magic resolves.

It was what it refuses to resolve.

When two branches genuinely disagree, Merge Magic does not guess.

For example:

• Both branches rename a function differently
• One branch deletes code while another modifies it
• Both branches change the same constant to different values
• Two changes appear semantically incompatible

In those cases, Merge Magic opens a decision card with context:

This conflict is between two commits:

🔴 HEAD        a1b2c3d   perf: bigger page size, shorter session timeout
                          Alice Chen · 2 days ago

🟢 MERGE_HEAD  9b79e0a   scale: max page size, longer session for enterprise
                          Bob Kumar · 1 day ago

The goal is not to hide hard decisions.

The goal is to make the easy ones disappear and make the hard ones clearer.

Three Surfaces, One Engine

Merge Magic runs in three places.

VS Code

A VS Code extension with an auto-mode dashboard.

When git merge produces conflicts, files resolve in parallel with a live progress view.

Terminal

A CLI that can register as a global Git merge driver:

npm install -g merge-magic
mergemagic setup
echo "* merge=mergemagic" >> .gitattributes

After that, git merge and git rebase can invoke the resolver inline.

This is especially useful for recurring conflicts during rebase replay.

CI

A GitHub Action can resolve PR conflicts server-side before a human review:

- run: npm install -g merge-magic

- env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: mergemagic ci --base "${{ github.base_ref }}"

The CI check posts a Markdown report to the Actions summary.

If a conflict requires a real human decision, the check fails loudly.

It does not silently pick a side.

What I Deliberately Do Not Claim

A lot of AI developer tools overclaim.

I tried hard not to.

It is not an AST merge

The mechanical pre-pass is a careful three-way line merge.

It is not tree-sitter.
It is not structural merging.
It is not a true AST-aware resolver.

That is a harder problem, and it is still on the roadmap.

Semantic warnings are heuristics

When the model says two changes may interact, that is not static analysis.

It is a heuristic.

Useful, but not authoritative.

The benchmark is not “better than Copilot”

Copilot’s smart-action resolver is not scriptable, so a clean automated head-to-head benchmark is not really possible.

Merge Magic’s benchmark reports match rate against known human resolutions on a corpus you provide.

That is useful.

It is also honest.

Why This Matters

The promise of AI in developer workflows should not be “trust the model blindly.”

It should be:

Remove the repetitive work.
Preserve human judgment where it matters.
Make the review surface clearer.

That is the philosophy behind Merge Magic.

It is not trying to replace code review.

It is trying to remove the part of conflict resolution that developers already know is mechanical.

Try It

VS Code

Search for Merge Magic in the Extensions Marketplace.

Or install it here:

Merge Magic on VS Code Marketplace

Terminal

npm install -g merge-magic
mergemagic demo

The demo runs in a temporary repository and will not touch your code.

Feedback I’m Looking For

I would especially value feedback on three things:

1. Does the verification floor catch enough?
   It catches type and lint failures, but not behavioral regressions.

2. Is the mechanical pre-pass too conservative?
   It currently defers anything ambiguous, even when an LLM might handle it well.

3. Is the CI mode too aggressive or too cautious?
   Auto-commit is opt-in, and Merge Magic refuses to push directly to main.

The most useful feedback is where it gets the resolution wrong.

Those cases are what improve the resolver, the prompt, and the pre-pass.

Merge conflicts are not going away.

But the boring ones should.