docx-cli: High-Fidelity Word Document Editing for AI Agents

docx-cli enables AI agents to edit Word documents with higher precision and lower cost

docx-cli is a command-line interface designed specifically for AI agents (such as Claude and Codex) to interact with .docx files without breaking formatting or corrupting the file structure. By providing agents with plain commands and an annotated-Markdown read view rather than requiring them to manipulate raw OOXML (Office Open XML), the tool significantly reduces token consumption and increases the success rate of complex document tasks.

Performance gains over raw OOXML manipulation

In a controlled A/B bake-off involving six real-world document tasks—including filling NDAs, redlining contracts, and restyling résumés—docx-cli demonstrated substantial improvements in both correctness and efficiency:

Higher Success Rates: Using a "weak" model like Claude Haiku, docx-cli solved 4.3 out of 6 tasks compared to 0.7 for the default skill. With a "strong" model like Claude Sonnet, docx-cli achieved a perfect 6/6 success rate, while the default skill capped at 4/6.
Reduced Token Costs: Input tokens were reduced by approximately 2.2–2.6× across both model tiers.
Faster Execution: Wall-clock time was reduced by 1.7–2.0×.
Reliability: 100% of docx-cli's outputs opened successfully in Microsoft Word, whereas the default skill produced files that Word could not open in roughly 14% of cases (5 of 36).

Technical Architecture: In-place XML Mutation

Unlike lossy models that re-emit entire documents, docx-cli uses in-place XML mutation. The AST (Abstract Syntax Tree) returned during a read operation is a view over the parsed XML tree; when an agent issues an edit or comment command, the CLI mutates the underlying XML nodes directly and serializes the result back to the file.

This approach ensures that elements not modeled in the AST—such as custom styles, theme colors, and schema extensions—survive the editing process because untouched regions are never re-emitted.

Stable Locators for Precise Addressing

To avoid the ambiguity of raw text, docx-cli employs a stable locator system that allows agents to address specific 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/enN (footnotes/endnotes), and tcN (tracked changes) are surfaced via list verbs.
Spans: Character offsets (0-based, start-inclusive, end-exclusive) can be used to target specific text within a paragraph (e.g., p3:5-20).

Key Features and Capabilities

Tracked Changes and Review Workflows

docx-cli supports native Word track-changes. When tracking is enabled, insert, edit, delete, and replace operations emit native <w:ins> and <w:del> tags. The tool provides three distinct read views to handle these changes:

--accepted: Renders clean text as if all changes were accepted.
--current: Shows CriticMarkup with [^tcN] footnotes for each change.
--baseline: Renders the document as it existed before changes were made.

Rich Content Handling

Equations: Round-trips OOXML <m:oMath> to LaTeX using a custom MathML–OMML adapter.
Images: Supports insertion from paths, data URIs, or URLs, with automatic HEIC–JPEG transcoding and SVG sanitization.
Tables: Operates on a merge-aware logical grid, allowing for structural edits (inserting rows/columns) without bisecting existing merged cells.
Styles: Allows for document-wide font updates and the creation or modification of specific style definitions in styles.xml.

Visual Verification

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

Integration as an Agent Skill

docx-cli is distributed as an Agent Skill, making it compatible with various AI harnesses including Claude Code, Codex, and Pi. It provides a SKILL.md file that teaches the agent the locator model and the redline/comment workflows, while deferring to the CLI's own --help commands for runtime specifics to ensure the documentation never goes stale.

Community Insights

Discussion among developers highlights the value of moving complex data manipulation out of the LLM's token space and into dedicated CLI tools. As one user noted:

"So much of the 'capability overhang' of AI can be addressed with tools like this--data manipulation etc without LLMs having to galaxy brain everything in token space"

Other contributors emphasized that while proprietary formats like .docx remain a challenge, providing high-fidelity CLI access is the most pragmatic way to handle the "relic" of the office suite format in professional environments.