Skip to content
Back to search

Docxodus

Swiss-army toolkit for .docx — faithful DOCX→HTML rendering, an in-browser block editor, Word-grade redlines with native tracked changes, and anchor-addressed markdown for LLM agents. .NET, WASM/TypeScript, Python, CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/JSv4/Docxodus with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/JSv4/Docxodus'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jsv4--docxodus/badge.svg)](/listings/jsv4--docxodus)

HTML

<a href="/listings/jsv4--docxodus"><img src="/api/listings/jsv4--docxodus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 371 lines
  1. <p align="center">
  2. <img src="docxodus-logo.png" alt="Docxodus" width="380">
  3. </p>
  4. <p align="center">
  5. <strong>Free your .docx files.</strong><br>
  6. Render them, edit them, diff them, and hand them to an agent — from .NET, the browser, Python, or the shell.
  7. </p>
  8. <p align="center">
  9. <a href="https://github.com/JSv4/Docxodus/actions/workflows/ci.yml"><img src="https://github.com/JSv4/Docxodus/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  10. <a href="https://www.nuget.org/packages/Docxodus"><img src="https://img.shields.io/nuget/v/Docxodus?label=nuget" alt="NuGet"></a>
  11. <a href="https://www.npmjs.com/package/docxodus"><img src="https://img.shields.io/npm/v/docxodus?label=npm" alt="npm"></a>
  12. <a href="https://pypi.org/project/docx-scalpel/"><img src="https://img.shields.io/pypi/v/docx-scalpel?label=pypi" alt="PyPI"></a>
  13. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  14. <a href="https://jandira-tech.github.io/neurotic_docx_bench/"><img src="https://raw.githubusercontent.com/jandira-tech/neurotic_docx_bench/main/docs/badges/redline-11-chill-neurotic-benched.svg" alt="neurotic_docx_bench"></a>
  15. </p>
  16. ---
  17. A `.docx` is a zip full of XML that only one program really understands. Docxodus is the toolkit that
  18. changes that: a **structure-aware OOXML engine** that reads Word documents faithfully, writes them
  19. back losslessly, and exposes them through whichever surface your program actually needs — an HTML
  20. render, a stable markdown projection, a stateful edit session, a tracked-changes redline, or a live
  21. in-browser editor.
  22. It runs as a **.NET library**, a **WebAssembly module in the browser**, an **npm/TypeScript package**,
  23. a **Python client**, an **MCP server for AI agents**, and three **CLI tools** — all over the same
  24. engine, so a document behaves the same everywhere.
  25. **It's JavaScript.** The npm package is plain ES modules with TypeScript types bundled: `import`
  26. it in the browser or in Node, pass a `File` or `Uint8Array`, `await` the result. There is no .NET
  27. to install and no server to run — the engine ships inside the package as WebAssembly.
  28. ```
  29. ┌───────────────────────────────────────────┐
  30. your .docx ──▶ │ Docxodus · one OOXML engine │ ──▶ .docx (lossless)
  31. └────┬─────────┬──────────┬──────────┬──────┘
  32. │ │ │ │
  33. render edit compare project
  34. ```
  35. Every screenshot below is real output, captured from the
  36. [NVCA model financing documents](https://nvca.org/model-legal-documents/) — the venture-financing
  37. forms that every startup lawyer actually redlines.
  38. ---
  39. ## Compare — a redline Word will open
  40. Docxodus compares two Word documents structurally — a docx diff, or a blackline if that is your
  41. firm's word for it — and emits **native Word tracked-changes markup**:
  42. `w:ins`, `w:del`, `w:moveFrom`/`w:moveTo`, and `w:pPrChange`. Not a text diff with highlighting — a
  43. file you can hand to opposing counsel, who accepts and rejects changes in Word as usual.
  44. ![A redlined venture financing agreement](docs/images/redline.png)
  45. One frame, four kinds of change, all detected automatically: a **struck definition** (red), an
  46. **inserted definition** (green), **word-level substitutions** inside an otherwise untouched sentence
  47. (`Series A` replacing a blank; `means` replacing `shall mean and include`), and a **move** — the
  48. interpretation clause struck at the bottom in purple and re-inserted at the top, linked as one
  49. operation rather than reported as an unrelated delete and insert. Note the list numbering: it
  50. renumbers as if every change were already accepted — the struck `(g)` is followed by the live
  51. `(g)`, exactly the duplicate-number display Word uses in All Markup view — so the letters a reader
  52. cites are the final document's.
  53. - **Round-trip contract:** `accept(compare(left, right)) ≡ right` and `reject(...) ≡ left`, verified
  54. at the block-text level.
  55. - **The diff is also data.** `GetRevisions()` returns typed revisions carrying stable
  56. `kind:scope:unid` anchors; `GetEditScriptJson()` returns the whole edit script as JSON, so you can
  57. drive a review UI or an approval workflow without parsing OOXML.
  58. - **Semantic verification.** `GetSemanticChanges()` returns a deterministic, versioned change set
  59. for text, formatting, styles, numbering, tables, sections, stories, review data, relationships,
  60. media, and opaque package changes while suppressing serialization-only noise;
  61. `GetSemanticChangesJson()` emits its JSON representation.
  62. - **Deliverable gate.** `DeliverableVerifier.VerifyDeliverable()` combines bounded package/schema
  63. validation, cross-part closure, workflow residue, baseline-aware findings, expected deltas, and
  64. digest-bound renderer artifacts into one canonical pass/failed report. Default report operations
  65. are also available through WASM/npm, Python, and MCP.
  66. - **Delivery change receipts.** `DeliveryChangeReceiptBuilder` binds one delivery into a
  67. canonical, hash-addressed record — source/delivered package identities, every normalized
  68. request and transaction with its undo/redo lineage, requested/derived/unexpected change
  69. attribution, typed semantic evidence, page citations pinned to a render fingerprint, and
  70. the digest of every artifact — and `DeliveryChangeReceiptVerifier` re-checks all of it
  71. from raw bytes, so a recipient can verify what an automated edit did (and that nothing
  72. else changed) without trusting the system that produced it. Core .NET today; the
  73. cross-surface ripple is tracked in #520.
  74. - **N-way consolidate.** Merge many reviewers' copies against one base into a single multi-author
  75. tracked-changes document, with a structured conflict report.
  76. - Headers and footers are compared too — the way Word's own "Headers and footers" option does.
  77. Two entry points share one engine:
  78. - **`DocxCompare.Compare`** — the front door, and the one to start from. It compares the
  79. *accepted* view of each input, as Word's Compare does, so documents that already carry tracked
  80. changes still produce a clean redline. The `redline` CLI and the browser package's
  81. `compareDocuments` go through it.
  82. - **`DocxDiff`** — the engine underneath. Call it directly when you want more than a redlined
  83. document: revisions as data, the edit script, semantic changes, N-way consolidation, or the
  84. engine's own defaults. Those defaults compare each input's raw markup, including any tracked
  85. changes it already has, which turns a revision-bearing input into whole-document churn unless you
  86. set `PreAcceptInputRevisions` (or `PreserveInputRevisions`).
  87. The older `WmlComparer` engine was removed in v11.0.0.
  88. See [`docs/architecture/ir_diff_engine.md`](docs/architecture/ir_diff_engine.md).
  89. ---
  90. ## Render — fidelity, not approximation
  91. DOCX → HTML that keeps the things naive converters drop: justification, style inheritance, legal
  92. numbering, tables, images, comments, headers and footers, and real footnotes with back-references.
  93. ![The NVCA model charter rendered to HTML](docs/images/render.png)
  94. - **Paginated mode** flows content into real page boxes with per-page numbers, page-anchored
  95. footnotes, and running heads — a print-accurate preview in the browser.
  96. - **Tracked changes render as `<ins>`/`<del>`** with author metadata and move-aware styling (that's
  97. exactly what the redline screenshot above is).
  98. - **Comments** render endnote-style, inline, or in a margin; annotations can be overlaid
  99. incrementally without re-converting the document (~0.3 ms to add one, vs. a full re-conversion).
  100. - `HtmlToWmlConverter` goes the other way.
  101. ---
  102. ## Project — a text view an LLM can actually address
  103. `WmlToMarkdownConverter` renders a document as markdown where **every block carries a stable id**.
  104. The same document, two views, one addressing system:
  105. ![Markdown projection beside the rendered document](docs/images/projection.png)
  106. An anchor like `{#p:body:09612b1c13…}` is content-derived and survives edits elsewhere in the
  107. document. That gives an agent something a raw text dump can't: a way to *point*.
  108. - Read the markdown, decide "rewrite the indemnification clause", write back to that anchor.
  109. - Anchors are shared across the whole stack — the same id addresses a projection block, a rendered
  110. DOM node (`data-anchor`), a diff revision, and an edit target.
  111. - Resolve intent to anchors by text, regex, kind, bookmark, or annotation id; enumerate and safely
  112. mutate native hyperlinks and multi-paragraph bookmarks — no re-walking the
  113. document.
  114. - Also exports to [OpenContracts](docs/architecture/opencontracts_export.md) format with PAWLS page
  115. layout and token positions, for NLP and document-analysis pipelines.
  116. ---
  117. ## Edit — programmatically, or in a browser
  118. `DocxSession` is a stateful, anchor-addressed editor over the live document. Every mutation returns a
  119. typed result envelope — no exceptions across the API boundary — and the document stays a real,
  120. valid `.docx` the whole time.
  121. Text and structure (replace, split, merge, insert, delete), tables (insert/delete rows and columns),
  122. formatting (character ranges, paragraph styles, lists, borders), headers and footers, page numbering,
  123. footnotes and endnotes, annotations, bounded undo/redo, and a raw-OOXML escape hatch for anything
  124. the markdown subset can't express. Set `TrackedChanges = RenderInline` and every edit lands as
  125. `w:ins`/`w:del` instead of an accepted change.
  126. `DocxEditor` is the browser editor built on top of it — framework-agnostic TypeScript, WASM engine,
  127. no server:
  128. ![The in-browser DOCX editor](docs/images/editor/editor-overview.png)
  129. The document you see is the document you get: edits go through the session, and **only the changed
  130. block re-renders** — so a structural op costs ~90–360 ms on a 346-block, 94-footnote filing
  131. template, not the ~6 s a full remount used to take. `save()` returns lossless bytes.
  132. The ribbon covers the Word most people use — fonts, colour and highlight, paragraph spacing and
  133. the numbering gallery, styles read from the document, find and replace, links, pictures, tables
  134. with merge and shading, page setup, tracked changes with accept/reject — and comments render the
  135. way Word renders them: the range highlighted inline, the thread as a bubble in the margin.
  136. Headers and footers are edited in place on the page.
  137. <p align="center">
  138. <img src="docs/images/editor/comments.png" alt="Comment bubbles beside the page" width="49%">
  139. <img src="docs/images/editor/paginated.png" alt="Page view with a footer being edited in place" width="49%">
  140. </p>
  141. More of the surface — ribbon anatomy, the comment gutter, in-page headers and footers, per-operation
  142. costs — is in [`docs/architecture/editor_ui_surface.md`](docs/architecture/editor_ui_surface.md).
  143. ---
  144. ## For AI agents
  145. Docxodus is built to be driven by a model. An agent reads a document as markdown in which every
  146. block carries an anchor id, edits by anchor instead of re-sending the file, and saves a `.docx`
  147. whose untouched formatting, numbering and footnotes are exactly what they were.
  148. | The agent needs to… | Use |
  149. |---|---|
  150. | Call tools over the Model Context Protocol | [`Docxodus.McpServer`](tools/mcp-server/README.md) — 23 tools over stdio: open, search, edit, format, comment, compare, track changes, save |
  151. | Script edits from Python | [`docx-scalpel`](python/README.md) — `pip install docx-scalpel`, no .NET install |
  152. | Call it from JavaScript or TypeScript, in a browser or Node, with no server | [`docxodus`](docs/npm-package.md) — `npm install docxodus`, import `docxodus/core`; ES modules with types included |
  153. | Shell out | `redline old.docx new.docx out.docx`, `docx2html document.docx` |
  154. The MCP server runs locally and makes no network calls once installed. It is the NuGet package
  155. `Docxodus.McpServer`, published with each release after 16.0.0; with the .NET 10 SDK installed, a
  156. client fetches and runs it with `dnx`:
  157. ```json
  158. {
  159. "mcpServers": {
  160. "docxodus": {
  161. "command": "dnx",
  162. "args": ["Docxodus.McpServer", "--yes"]
  163. }
  164. }
  165. }
  166. ```
  167. `dotnet tool install -g Docxodus.McpServer` installs it as the `docxodus-mcp` command instead, and
  168. from a clone it runs with `dotnet run --project tools/mcp-server`.
  169. [`llms.txt`](docs/llms.txt) is a plain-text index of the same ground for a model to read: each
  170. common task — compare, render, convert to markdown or PDF, edit, accept and reject changes — with
  171. the call that does it on every surface. It is also served at
  172. <https://jsv4.github.io/Docxodus/llms.txt>.
  173. ---
  174. ## Get started
  175. <table>
  176. <tr><th align="left">.NET</th><th align="left">JavaScript / TypeScript</th></tr>
  177. <tr valign="top"><td>
  178. ```bash
  179. dotnet add package Docxodus
  180. ```
  181. ```csharp
  182. using Docxodus;
  183. var redline = DocxCompare.Compare(
  184. new WmlDocument("v1.docx"),
  185. new WmlDocument("v2.docx"));
  186. redline.SaveAs("redline.docx");
  187. ```
  188. </td><td>
  189. ```bash
  190. npm install docxodus
  191. ```
  192. ```ts
  193. import { initialize, compareDocuments } from 'docxodus/core';
  194. await initialize();
  195. const redline = await compareDocuments(v1, v2);
  196. ```
  197. Use `docxodus/core` for the engine in Node or browser code. Browser editor APIs such as
  198. `DocxEditor` and `mountRibbon` are available from `docxodus`.
  199. </td></tr>
  200. <tr><th align="left">Python</th><th align="left">CLI</th></tr>
  201. <tr valign="top"><td>
  202. ```bash
  203. pip install docx-scalpel
  204. ```
  205. ```python
  206. from docx_scalpel import open_session
  207. with open_session(docx_bytes) as s:
  208. s.replace_text(anchor, "new text")
  209. out = s.save()
  210. ```
  211. </td><td>
  212. ```bash
  213. dotnet tool install -g Redline
  214. redline old.docx new.docx out.docx
  215. ```
  216. Also `Docx2Html` and `Docx2OC`, plus
  217. [standalone binaries](https://github.com/JSv4/Docxodus/releases)
  218. for Windows, Linux and macOS.
  219. </td></tr>
  220. </table>
  221. Opening an editor in a page is a few lines more — see [`npm/examples/editor.html`](npm/examples/editor.html)
  222. for a complete ribbon implementation, and [`docs/npm-package.md`](docs/npm-package.md) for the
  223. TypeScript API and React hooks.
  224. ---
  225. ## Where it runs
  226. | Surface | Package | Notes |
  227. |---|---|---|
  228. | .NET 10 library | [`Docxodus`](https://www.nuget.org/packages/Docxodus) (NuGet) | The engine. Everything else wraps it. |
  229. | JavaScript / TypeScript (browser and Node) | [`docxodus`](https://www.npmjs.com/package/docxodus) (npm) | Plain ES modules with bundled types; the engine is WebAssembly inside the package, so there is no .NET install and no server. Web Worker and React hooks included. |
  230. | Python | [`docx-scalpel`](https://pypi.org/project/docx-scalpel/) (PyPI) | Long-running host process, so an agent can issue dozens of edits against one open session. *Beta; wheels for linux-x64/arm64, osx-arm64, win-x64.* |
  231. | CLI | `Redline`, `Docx2Html`, `Docx2OC` | `dotnet tool install -g`, or download a self-contained binary. |
  232. | MCP server | [`Docxodus.McpServer`](https://www.nuget.org/packages/Docxodus.McpServer) (NuGet) | Stdio server for AI agents, command `docxodus-mcp`. `dotnet tool install -g`, or run with `dnx`. |
  233. | DOCX → PDF | [`@docxodus/export`](https://www.npmjs.com/package/@docxodus/export) (npm) | Paginated HTML and PDF from Node or `docxodus convert`, through a pinned Chromium. |
  234. ---
  235. ## What else is in the box
  236. | | |
  237. |---|---|
  238. | **DocumentBuilder** | Merge and split DOCX files, with section and style fidelity |
  239. | **OpenXmlRegex** | Regex search/replace across DOCX |
  240. | **RevisionProcessor** | Accept and reject tracked revisions, byte-to-byte |
  241. | **FormattingAssembler** | Resolve and flatten inherited formatting |
  242. | **MetricsGetter** | Extract document metrics — styles, fonts, languages |
  243. | **ExternalAnnotationProjector** | Overlay annotations onto rendered HTML without touching the DOCX |
  244. ---
  245. ## Documentation
  246. Design docs for every subsystem live in [`docs/architecture/`](docs/architecture/). The ones worth
  247. reading first:
  248. | Doc | What it covers |
  249. |---|---|
  250. | [`ir_diff_engine.md`](docs/architecture/ir_diff_engine.md) | `DocxDiff` — pipeline, edit script, settings, parity with Word |
  251. | [`semantic_diff.md`](docs/architecture/semantic_diff.md) | Stable semantic-change schema, package coverage, canonicalization, and limits |
  252. | [`docx_agent_server.md`](docs/architecture/docx_agent_server.md) | The MCP server — every tool, its arguments and result shape |
  253. | [`docx_mutation_api.md`](docs/architecture/docx_mutation_api.md) | `DocxSession` — full surface, anchor lifecycle, error catalog, markdown subset |
  254. | [`native_content_controls.md`](docs/architecture/native_content_controls.md) | Native Word content-control registry, fills, binding/lock safety, and transports |
  255. | [`delivery_change_receipt.md`](docs/architecture/delivery_change_receipt.md) | Deterministic delivery receipts, LIFO lineage, exact semantic/package artifacts, privacy, citations, and verification |
  256. | [`markdown_projection.md`](docs/architecture/markdown_projection.md) | The projection spec and anchor format |
  257. | [`docx_converter.md`](docs/architecture/docx_converter.md) | `WmlToHtmlConverter` internals |
  258. | [`editor_ui_surface.md`](docs/architecture/editor_ui_surface.md) | The browser editor, control by control |
  259. | [`ooxml_corner_cases.md`](docs/ooxml_corner_cases.md) | Where Word disagrees with the spec — and what we do about it |
  260. ---
  261. ## Build and test
  262. ```bash
  263. dotnet build Docxodus.sln # build
  264. dotnet test Docxodus.Tests/Docxodus.Tests.csproj # .NET unit tests
  265. cd npm && npm install && npx playwright install chromium
  266. npm run build && npm test # WASM + Playwright browser tests
  267. ```
  268. `npm run build` compiles the library to WebAssembly (`scripts/build-wasm.sh`) and bundles the
  269. TypeScript — re-run it after touching C#, TypeScript, or the test harness, or the browser tests will
  270. run against stale artifacts. Release builds treat warnings as errors. See
  271. [`CLAUDE.md`](CLAUDE.md) for the full development workflow and repository layout.
  272. ## Requirements
  273. The .NET 10.0 SDK, to build from source. Consumers of the npm and PyPI packages need no .NET
  274. install of their own.
  275. ## License
  276. MIT — see [LICENSE](LICENSE).
  277. Contributors are asked to sign the [Contributor License Agreement](CLA.md); the CLA bot prompts
  278. you on your first pull request, and signing is a single comment.
  279. ---
  280. *Built on the shoulders of [Open-Xml-PowerTools](https://github.com/OfficeDev/Open-Xml-PowerTools).
  281. Thanks to Eric White, Thomas Barnekow, and all original contributors.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.