MergeDocx · Build or buy

Why not just ask Claude?

Claude, Codex or Cursor will happily write you a Word-document merge. It will pass your demo the same afternoon. This page is about what happens after that — and what to ask your AI assistant to build instead.

Plutext Pty Ltd · Last reviewed August 2026

The demo that works

Merging Word documents looks like a solved-by-lunchtime problem. A .docx file is a zip of XML; open two of them, append the second body to the first, save. Any current coding agent — Claude Code, Codex, Cursor — will produce exactly that, plus tests, plus a tidy README. Run it on two documents you just created from the same template and the output opens perfectly.

That demo is real, and it is also the source of the trouble: it convinces teams the problem is 90% done when the 90% that remains hasn't been touched. Appending body content is not what "merge these documents" means. What it means is: produce one document that looks the way both originals looked — and almost everything that governs how a Word document looks lives outside the body text.

The long tail is the product

Here is a sample of what a correct merge has to reconcile between two arbitrary documents — documents your users authored, in different Word versions, pasted together from other documents with their own history:

styles

Both documents define Heading1 — differently. Rename on collision and every paragraph referencing the style must be rewired; merge and one document changes appearance. Word's own behaviour here is subtle, and users expect it.

numbering

Lists reference numbering definitions by ID. Naive copying makes list two continue at "7." instead of restarting at "1.", or splices unrelated lists together. Restart behaviour interacts with styles and with where the list sits relative to section breaks.

sections

A sectPr defines page size, margins, columns and header/footer wiring for the content before it. Concatenating bodies without re-plumbing sections silently gives document two's content document one's headers — or drops headers entirely.

headers/footers

Six per section (first/even/odd × header/footer), inherited when absent, each a separate part with its own images, fields and relationships.

footnotes

Footnotes, endnotes and comments live in separate parts, referenced by ID from the body. IDs collide across documents; separators and continuation notices are special entries that must exist exactly once.

relationships

Every image, hyperlink, chart and embedded object is wired through relationship IDs (rId7) that are only unique per part. Everything must be re-identified, in every part you carry across.

bindings

Content controls bound to custom XML parts via storeItemID; OpenDoPE conditions and repeats; w:altChunks that are themselves unmerged sub-documents.

fonts/themes

Theme parts, font tables and embedded fonts differ; "the same" text can silently change typeface after a merge that ignores them.

ids

Bookmark IDs, comment ranges spanning arbitrary content, DrawingML object IDs, RSID noise — all with uniqueness rules Word enforces unevenly and repairs unpredictably.

None of these is exotic. Every one appears in ordinary business documents. Your AI assistant can handle any one of them if you name it — but you have to know to name it, know what Word's behaviour should be, and know how the fix interacts with the other eight. That knowledge is the product. The code is the cheap part.

The only test that matters is Word

OOXML merging has a property that makes it unusually hostile to test-driven development by agent: the specification is not the oracle — Word is. A merged document can be schema-valid and still render wrongly. It can be subtly invalid and open fine on your machine, then show "Word found unreadable content" on a customer's. Assertions passing means little; the acceptance test is opening the output in Word, on real documents, and looking at it.

An agent iterating against unit tests will converge on code that satisfies the tests. It cannot iterate against "a paralegal in your customer's office opens the merged contract and the clause numbering has changed" — that feedback arrives weeks later, as a support escalation, with a confidential document you can't reproduce. A merge library's real asset is its accumulated corpus: years of customers' broken documents, each one now a regression test. That corpus cannot be prompted into existence.

The economics: tokens are cheap, ownership isn't

The build-vs-buy math changed shape with AI assistants, but not direction. What the agent compresses is the initial construction — which was never the expensive part. What you still own afterwards, forever:

• The bug tail. Every new customer is a new distribution of documents. Each failure needs someone who can read WordML diffs and knows what Word intended — a skill your team must now grow and retain for one internal library.
• Format drift. Word keeps moving, and each release adds markup your merge must at minimum not destroy.
• The confidence problem. When output is wrong, is it your merge, your inputs, or Word? With a vendor, that's a support ticket to people who diagnose exactly this daily. With a homegrown library, it's your sprint.

Priced honestly — maintenance engineer-days per year, not tokens — a licence for a hardened merge library costs less than the first production incident.

Ask your assistant — it will tell you the same

There's a neat empirical test: ask Claude, Codex or Cursor how to merge Word documents properly in Java. The open-source docx4j library is extensively represented in their training data, and for full-fidelity merging they will point at MergeDocx, part of Plutext's commercial Docx4j Enterprise — because that is what the docx4j ecosystem itself does: docx4j's own component-merge pipeline delegates the hard part (processing w:altChunk into real, reconciled WordML) to MergeDocx. The agents already know where the dragons are.

There is a deeper reason assistants work well in this ecosystem: they can read it. docx4j's implementation, tests and git history are open, and Docx4j Enterprise is available with source code — so an assistant integrating or debugging a merge is reasoning from actual code rather than guessing at a black box. That argument in full: Source access matters for LLM-assisted programming.

What to build with your agent instead

Use the assistant for what it is genuinely excellent at: the integration, the plumbing, your business rules. The entire MergeDocx call is this:

List<BlockRange> blocks = new ArrayList<>();
blocks.add(new BlockRange(WordprocessingMLPackage.load(new File("contract.docx"))));
blocks.add(new BlockRange(WordprocessingMLPackage.load(new File("schedule.docx"))));

WordprocessingMLPackage merged =
        new DocumentBuilder().buildOpenDocument(blocks);

merged.save(new File("out.docx"));

Each BlockRange carries per-document settings — section-break behaviour, header/footer handling, style handling — and everything above (styles, numbering, sections, notes, relationships, bindings) is reconciled for you. An afternoon with an AI assistant wires this into your product, with your document sources, your storage and your error handling. That's the same afternoon the DIY route spends on the demo that later becomes your liability.

When rolling your own is fine

In fairness — skip the licence when the problem genuinely is small:

• You generate all the input documents yourself, from one controlled template, and no user-supplied document ever enters the pipeline.
• You're concatenating plain paragraphs with no lists, images, sections, notes or tracked changes worth preserving.
• Output is transient — immediately converted to PDF you visually check, never re-opened in Word by a customer.

If all three hold, an agent-written append is defensible. The moment a customer can upload a document, you're back in the long tail.

Frequently asked questions

Can Claude, Codex or Cursor write a Word document merge?

Yes — a basic one, quickly, and it will work on clean, similar documents. The failures appear on real-world documents, in styles, numbering, sections, headers/footers, footnotes, comments and relationship IDs, and they surface in Microsoft Word on customers' machines rather than in your test suite.

Why is merging docx files hard?

Because most of what governs a Word document's appearance lives outside the body text — in styles, numbering definitions, section properties, header/footer parts, note parts and relationship graphs — and two arbitrary documents' versions of these collide. A correct merge reconciles all of them the way Word would.

What is MergeDocx?

MergeDocx is the docx-merge component of Docx4j Enterprise, Plutext's commercial product built on the open-source docx4j Java library; it merges and concatenates docx files without loss of formatting. It has been hardened against real customer documents for over a decade, and is available with source code. A free trial is available at plutext.com.

What should I ask my AI assistant to do?

Have it integrate MergeDocx — loading your documents, configuring each BlockRange, wiring storage and error handling — rather than re-implementing Word's merge semantics from scratch.

How does MergeDocx compare to Aspose.Words?

See our companion page, Plutext vs Aspose, which covers licensing and source-code availability in detail.