How to add tracked changes to a DOCX programmatically

What a Word tracked change actually is

A .docx file is a ZIP package containing related XML parts. In the main document part, WordprocessingML represents inserted and deleted content with revision elements such as w:ins and w:del. A simplified replacement looks like this:

<w:del w:author="Reviewer" w:id="12">
  <w:r><w:delText>30 days</w:delText></w:r>
</w:del>
<w:ins w:author="Reviewer" w:id="13">
  <w:r><w:t>45 days</w:t></w:r>
</w:ins>

Real documents add run formatting, tables, hyperlinks, fields, notes, content controls, existing revisions, and other package relationships. A correct edit must preserve that structure and maintain two useful readings:

• Reject the revision: recover the document before the edit.
• Accept the revision: produce the intended document after the edit.

Writing a new string into document.xml is therefore not enough. The operation needs an explicit target, revision semantics, attribution, and validation of the resulting package.

Choose the input that matches what you know

You know the exact old and new wording

Use an explicit worklist. This is the most bounded option for approved changes.

You have an original and a revised DOCX

Compare the two documents and create one native tracked-changes redline.

You have a natural-language instruction

Use an agent through MCP to inspect the document, turn the request into bounded operations, and save the result.

Apply an exact edit as a tracked change

1. Install the CLI and identify the input

cargo install stemma-cli
stemma validate agreement.docx

Validation reports the input byte count and SHA-256. Binding those values into a worklist makes stale-document mistakes fail before mutation.

2. Describe the approved change

Save the following as changes.json, using the values printed by validation:

{
  "schema": "stemma.worklist.v0",
  "input": {
    "sha256": "<sha256 printed by stemma validate>",
    "bytes": 48271
  },
  "author": "Approved Reviewer",
  "changes": [
    {
      "id": "payment-term",
      "old": "Payment is due within 30 days.",
      "new": "Payment is due within 45 days.",
      "expected_matches": 1
    }
  ]
}

The expected match count is part of the instruction. If the old wording is absent or occurs more than once, Stemma refuses the worklist rather than choosing a location silently.

3. Create a new redline

stemma apply agreement.docx \
  --worklist changes.json \
  -o agreement-redline.docx

On success, Stemma writes a new DOCX and a receipt. It never overwrites the input or an existing output path. The receipt records the artifact identities and the outcome of every worklist item.

4. Check both revision outcomes

stemma resolve agreement-redline.docx \
  -o agreement-accepted.docx --accept-all

stemma resolve agreement-redline.docx \
  -o agreement-rejected.docx --reject-all

stemma validate agreement-redline.docx

Open the redline in Word for the reviewer-facing check. Accept-all should contain the approved wording; reject-all should restore the original reading.

Create a redline from two DOCX versions

If the revised file already exists, comparison is the shorter path:

stemma compare as-sent.docx as-returned.docx \
  -o changed.docx \
  --author "Approved Reviewer"

The output contract is direct: rejecting every discovered change reconstructs as-sent.docx, while accepting every change reconstructs as-returned.docx.

Give an AI agent a bounded DOCX editor

Stemma also ships an MCP server with prebuilt binaries. From the directory containing the documents, add it to Claude Code:

claude mcp add --scope local stemma -- npx -y @stemma-sh/mcp

Then give the agent a concrete document outcome, for example:

The model reasons about intent and calls tools; Stemma owns document parsing, revision operations, validation, and create-new delivery. Content returned through tool calls may be received by your MCP client or configured model provider, so review that provider's data policy.

Current boundaries

Stemma is pre-1.0. The focused CLI worklist supports explicit old-to-new replacements in top-level body paragraphs, with match-count guards and optional block or range restrictions. The engine and MCP server expose broader workflows, but unsupported structures and ambiguous targets are reported rather than treated as successful edits.

Before building a durable integration, read the current fidelity contract, stability policy, and worklist reference.