docx-cli: Enabling AI Agents to Edit Word Documents with High Fidelity

docx-cli: Enabling AI Agents to Edit Word Documents with High Fidelity

docx-cli optimizes AI agent interaction with Word documents

docx-cli is a specialized CLI designed for AI agents (such as Claude and Codex) to read, edit, and comment on .docx files while maintaining full format fidelity. Unlike traditional methods where agents attempt to modify the underlying OOXML (Office Open XML) directly—which often results in corrupted files and high token consumption—docx-cli provides agents with plain commands and an annotated-Markdown read view. This approach ensures that custom styles, theme colors, and embedded objects survive the editing process.

Performance benchmarks: docx-cli vs. default agent skills

In a controlled A/B bake-off involving six real-world document tasks (including filling NDAs, redlining contracts, and authoring journals), docx-cli significantly outperformed default agent skills across two model tiers:

  • Success Rates: On the "weak" Haiku tier, docx-cli solved 4.3/6 tasks compared to 0.7/6 for the default skill. On the "strong" Sonnet tier, it achieved a perfect 6/6 versus 4/6.
  • Token Efficiency: docx-cli reduced input tokens by approximately 2.2·2.6·, lowering costs and increasing speed.
  • Latency: Wall-clock time was reduced by 1.7·2.0· across both tiers.
  • Reliability: 100% of docx-cli outputs opened in Microsoft Word on the first try, whereas the default skill produced several files that Word could not open.

Core technical architecture

In-place XML mutation

Instead of re-emitting a document from a lossy model, docx-cli treats the AST (Abstract Syntax Tree) as a view over the parsed XML tree. When an agent executes an edit or comments add command, the CLI mutates the underlying XML nodes directly and serializes the changes back to the file. This ensures that any element not explicitly modeled in the AST, such as proprietary schema extensions or complex theme colors, remains untouched and intact.

Stable locators and addressing

To avoid the fragility of raw text offsets, docx-cli uses a locator system to address document elements precisely:

  • Block IDs: pN (paragraph), tN (table), and sN (section break) are derived from document order.
  • Entity IDs: cN (comment), imgN (image), linkN (hyperlink), fnN (footnote), and enN (endnote) are surfaced via list verbs.
  • Spans: Character offsets are 0-based, start-inclusive, and end-exclusive (e.g., p3:5-20 targets characters 5 through 19 of paragraph 3).

Rich content handling

docx-cli implements several advanced features to handle complex Word elements:

  • Equations: Round-trips OOXML <m:oMath> to LaTeX using a custom MathML–OMML adapter.
  • Tracked Changes: Native <w:ins> and <w:del> tags are used for redlining. The CLI supports three read views: --accepted (clean text), --current (CriticMarkup with footnotes), and --baseline (pre-change text).
  • Images: Supports insertion from paths, data: URIs, or HTTP(S) URLs, with automatic HEIC–JPEG transcoding.
  • Styles: Allows editing of style definitions in styles.xml, enabling global changes (e.g., "make all Heading 1s green") without modifying every instance in the document body.

Command and Workflow Reference

Read and Query

Agents use docx read to get a Markdown representation of the document, supplemented by HTML-comment annotations (e.g., <!-- docx:p pN style="Caption" -->) that provide structural hints about styles, alignment, and spacing.\n

Mutation

Mutators change the file in place. Key commands include:

  • docx replace: Substitutes patterns while preserving run formatting.
  • docx edit: Modifies content at a specific locator, supporting plain text, Markdown, or raw runs.
  • docx insert: Adds content before or after a locator.
  • docx comments add: Attaches comments to specific spans or phrases.

Visual Verification

docx render allows agents to verify their work by driving Microsoft Word (via osascript or PowerShell COM) or LibreOffice to produce a PDF, which is then rasterized into PNG or JPG images using a bundled PDFium WASM package.

Installation and Agent Integration

docx-cli is distributed as an Agent Skill, compatible with Claude Code, Codex, and Pi. It can be installed via npx skills add kklimuk/docx-cli or as a standalone binary for Linux, macOS, and Windows. For Claude Code specifically, users can use the /plugin marketplace add kklimuk/docx-cli command.

Sources