Compare two Word documents (.docx) and get a native Track Changes redline — as if a human editor had revised the old draft into the new one with "Track Changes" switched on.
English | 简体中文
track-changes docx-diff word-compare redline document-comparison ooxml kimi-skill agent-swarm
In the age of AI-assisted writing, documents iterate fast. A paper, a report, a contract — every prompt produces a new version, and suddenly you have v3-final-FINAL.docx chaos. You want to know exactly what changed between two drafts, in the one format every collaborator understands: Word's native revision mode, where each edit can be individually accepted or rejected.
Existing options fall short:
- ☁️ Online comparison tools require uploading your unpublished manuscript — a privacy no-go for pre-publication research.
- 📄 Word's built-in Compare works, but is manual, GUI-bound, and can't be scripted into an automated pipeline.
- 🐍
difflib& friends give you text diffs, not a Word file with real<w:ins>/<w:del>revision marks.
This tool fills the gap: one command in, one tracked-changes .docx out — open it in Microsoft Word, WPS, or LibreOffice and review every insertion and deletion in the familiar "All Markup" view.
Two synthetic demo documents (text + figure + table) are compared — no real data involved:
| Page 1 — title, inline edits, deleted caption, replaced figure | Page 2 — table cell edit, new row, rewritten conclusion, new section |
|---|---|
 |
 |
Notice the details:
- 🔤 Word-level inline revisions —
12%→1218%,sharplymoderately - 🖼️ Figure replacement tracked — the old chart is marked deleted with its original bytes preserved, the new chart marked inserted
- 📊 Table edits — a changed cell (
4.5→4.3) and an inserted row (Delta) - ➕➖ Whole-paragraph insertions & deletions — the removed caption, the new "Next Steps" section
Try it yourself with the files in examples/:
python3 scripts/compare_docx_tracked.py examples/demo_v1.docx examples/demo_v2.docx out.docx --author "You"✍️ The output is a working document, not a report.
Real <w:ins> / <w:del> revisions with unique IDs, author, and date; w:trackChanges switched on automatically. Open the result and keep editing — accept or reject each change individually, in Word, WPS, or LibreOffice.
🔍 Word-level precision, not paragraph-level mush.
Modified paragraphs get fine-grained inline diffs — 12% → 1218% — instead of crude whole-paragraph delete+insert. Reviewers see the actual edit, not two walls of text.
🖼️ Lossless in both directions — images included. A replaced figure keeps the old image's original bytes inside its deletion mark, so "reject change" truly restores the old picture. Reject-all gives you the old document back, byte for byte.
✅ Every output is machine-verified, not hoped-for. The bundled verifier runs 7 automated checks on every redline: simulated accept all must equal the new file, simulated reject all must equal the old file, plus structural checks on revision IDs, deleted content, references, and image bytes. You never ship a redline you haven't proven correct.
🪶 Radically lightweight and auditable.
One Python script + lxml. No runtimes, no SDKs, no prebuilt binaries, nothing to install or compile. You can read the entire diff engine in one sitting — and trust it, because there's nothing hidden inside.
🔒 Private by default. 100% local. No upload, no network call, no account. Safe for unpublished manuscripts and confidential contracts.
🤖 Agent-native. Doubles as a Kimi skill — say "compare these two drafts with track changes" and get a verified redline back, hands-free. Scripts, verification, and failure-mode knowledge ship together in the repo.
🧪 Battle-tested in a real writing workflow. Born from iterating an academic paper across many AI-assisted drafts, and hardened by a blind swarm-style evaluation that caught a genuine image-fidelity bug before release. See EVALUATION.md.
Install from PyPI (recommended):
pip install docx-trackdiffRequirements for the from-source path: Python 3.8+, lxml (pip install lxml). LibreOffice optional (render check only).
# 1. Generate the tracked-changes document
docx-trackdiff OLD.docx NEW.docx OUTPUT.docx --author "Your Name"
# 2. Verify (7 automated checks)
docx-trackdiff-verify OUTPUT.docx OLD.docx NEW.docx
# 3. Optional render check
soffice --headless --convert-to pdf OUTPUT.docxgit clone https://github.com/stephenlzc/docx-trackdiff.git
cd docx-trackdiff
# 1. Generate the tracked-changes document
python3 scripts/compare_docx_tracked.py OLD.docx NEW.docx OUTPUT.docx \
--author "Your Name" --date "2026-08-15T00:00:00Z"
# 2. Verify (mandatory — 7 automated checks)
python3 scripts/verify_tracked.py OUTPUT.docx OLD.docx NEW.docxOpen OUTPUT.docx in Word → Review tab → All Markup. Accept or reject each change individually.
| Flag | Default | Meaning |
|---|---|---|
--author |
Editor |
Revision author shown in Word's markup panel |
--date |
today | Revision timestamp |
--threshold |
0.45 |
Paragraph similarity cutoff: above → inline word-level diff; below → whole-paragraph delete+insert |
This repo doubles as a Kimi agent skill. Clone it (or download the ZIP) and drop the folder into your Kimi skills directory (~/.kimi-code/skills/ or ~/.agents/skills/), then simply say:
"对比一下这两个版本的 docx，给我一份修订模式的文件" "Compare these two Word documents with track changes"
The agent reads SKILL.md, runs the bundled scripts, verifies the output, and hands you the redline — no manual steps.
It is also distributed to other agents via skill marketplaces — SkillsMP, SkillsLLM, LobeHub, and ClawHub — so Claude Code, Codex, and ChatGPT can call docx-trackdiff directly.
- Paragraph alignment —
difflib.SequenceMatcherover normalized text (curly quotes, dashes, spaces folded) aligns paragraphs between versions; a DP second pass pairs up "modified" paragraphs inside replace blocks (similarity ≥ threshold). - Word-level diff — modified paragraphs are tokenized and diffed; runs are split at diff boundaries while preserving original formatting. Paragraphs whose diff boundary crosses an atomic element (image, equation, hyperlink) fall back to whole-paragraph delete+insert by design.
- OOXML surgery, done right — deleted paragraphs are deep-copied with their formatting, converted to
w:delText, paragraph marks flagged, relationship IDs remapped, and old image bytes copied into the package so reject-all is lossless.w:trackChangesis injected at the schema-correct position insettings.xml. - Verification — unique revision IDs, no stray
w:tinsidew:del, no dangling references, accept/reject round-trip equality, deleted-content coverage, author/date presence, and old-image byte preservation.
Structure-aware throughout: headings, styles, tables, footnotes, hyperlinks, equations (OMML), and section layout are preserved from the new version.
See references/ooxml-revision-rules.md for the full rulebook and known failure modes.
- Compares the main document body (including table cells); comments and footnote content are not diffed
- A few paragraphs containing images/equations may appear as whole-paragraph delete+insert (designed fallback)
- Verified via LibreOffice + XML-level simulation; for high-stakes use, eyeball the result in desktop Word's All Markup view
.docfiles must be converted to.docxfirst
| docx-trackdiff | Online comparers | Word Compare | Python-Redlines | Aspose / GroupDocs | |
|---|---|---|---|---|---|
Native Word revisions (<w:ins>/<w:del>) |
✅ | ✅ | ✅ | ✅ | |
| 100% local / no upload | ✅ | ❌ | ✅ | ✅ | |
| Self-verifying (7 automated checks) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Image byte-lossless (reject restores old pic) | ✅ | ❌ | |||
| Zero dependencies (pure Py + lxml) | ✅ | — | — | ❌ (engine binaries) | ❌ (runtime/license) |
| Free & open source (MIT) | ✅ | ✅ (paid Office) | ✅ | ❌ (commercial) | |
| Usable as an AI agent skill | ✅ | ❌ | ❌ | ❌ |
Bottom line: if you need a private, local, provably-correct redline that an AI agent can call, docx-trackdiff is the option that ticks all the boxes.
This skill was not designed in the abstract — it was born from a real workflow. While iterating on an academic paper across multiple AI-assisted revisions, Big Stephen needed to see exactly what changed between drafts. The entire pipeline — diff algorithm, OOXML revision markup, verification harness, and this very skill packaging — was implemented through Kimi K3's Agent Swarm (by Moonshot AI): a coder subagent built and hardened the scripts, and a swarm-style evaluation round (paired with-skill vs. baseline runs, blind grading by a verifier subagent) caught and fixed a real image-fidelity bug before release.
The headline results of that evaluation: the with-skill run finished in ~1 minute versus ~15 minutes for a competent from-scratch baseline, with zero judgment errors. And the blind grader earned its keep — it caught a genuine image-fidelity defect (a replaced figure's old bytes were silently lost, so "reject change" would have restored the wrong picture) that the skill's own text-only verifier could not see. The fix and two hardened verifier checks (now 7 total) came straight out of that loop. Full report: EVALUATION.md.
It worked so well in daily use that it was distilled into this reusable skill and open-sourced. Built with Kimi K3. 🌒
- Author: Big Stephen — idea, requirements, real-world testing
- Co-author: Kimi K3 Agent Swarm by Moonshot AI (@MoonshotAI · Kimi-K3) — implementation, verification, packaging
Does it upload my documents? No. Everything runs 100% locally — no network calls, no accounts, no uploads. Safe for unpublished manuscripts and confidential contracts.
What's the difference between docx-trackdiff and python3 scripts/compare_docx_tracked.py?
Same engine. docx-trackdiff is the installed CLI (after pip install docx-trackdiff); the scripts/ path runs straight from a cloned repo without installing.
Can it compare .doc files?
Not directly — convert to .docx first (e.g. libreoffice --headless --convert-to docx file.doc).
Does it handle tables, images, footnotes, and equations? The main body — including table cells, images, hyperlinks, OMML equations, and section layout — is preserved from the new version. Footnote content and comments are not diffed yet.
How do I know the redline is correct?
Run docx-trackdiff-verify OUTPUT.docx OLD.docx NEW.docx. It runs 7 checks and prints PASS/FAIL per check, exiting non-zero on any failure.
Can an AI agent use it? Yes. It ships as a Kimi skill, and is distributed to Claude Code / Codex / ChatGPT via agent-skill marketplaces (SkillsMP, SkillsLLM, LobeHub, ClawHub).
MIT — use it anywhere, attribution appreciated.
docx track-changes word-diff redline document-comparison ooxml python kimi kimi-k3 moonshot-ai agent-skill ai-writing diff-tool word-documents revision-tracking