{"slug": "show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees", "title": "Show HN: A DOCX editing library inspired by Rosyln's syntax trees", "summary": "A new open-source library called docxtor, published on GitHub by Eazydraft and distributed as the npm package @lucio-ai/docxtor, gives AI agents a structured interface for reading, editing and reviewing .docx files by applying targeted patches directly to the underlying document XML rather than converting documents to plain text and reconstructing them. docxtor creates tracked changes and anchored comments, resolves revisions by ID or author, and preserves formatting, styles, numbering, headers, footers and tables outside edited regions; it ships with a self-contained agent skill for Claude Cowork/Claude.ai, Codex, Cursor, Gemini CLI and GitHub Copilot, and requires Node.js 20 or newer. The CLI exposes commands including view, revisions, replace, comment, comments, edit, accept/reject and metadata, with replace and edit writing tracked changes by default attributed via --author unless --untracked is passed.", "body_md": "**Precise, revision-aware editing for Microsoft Word documents. Built for AI agents.**\n\ndocxtor gives AI agents and applications a structured interface for reading, editing, and reviewing `.docx` files.\n\nCreate tracked changes, add comments anchored to specific passages, resolve revisions individually, and modify document content without rewriting the entire file.\n\nUnlike approaches that convert documents to plain text and reconstruct them, docxtor applies targeted patches directly to the underlying document XML. Formatting, styles, numbering, headers, footers, tables, and everything else outside the edited regions are preserved.\n\nWorks with Claude, Codex, Cursor, Gemini CLI, GitHub Copilot, and any agent that supports skills.\n\nAsk your agent to make changes in plain language:\n\nChange the payment terms to net 60 days and the delivery window to ten business days. Mark both as tracked changes and save the result as a new file.\n\nReview the counterparty's revisions. Reject changes involving monetary amounts or dates, accept everything else, and summarize what was rejected.\n\nAdd a comment to the liability clause asking the other party to reconsider the proposed cap.\n\nThe resulting document opens directly in Microsoft Word, with native tracked changes and comments.\n\ndocxtor ships with a self-contained agent skill that teaches compatible agents how to inspect and edit Word documents.\n\n**Claude Cowork / Claude.ai**\n\n1. Download `docxtor-skill.zip` from the[latest release](https://github.com/Eazydraft/docxtor/releases/latest) .\n2. Upload it under Customize → Skills.\n3. Enable code execution.\n\n**Codex, Cursor, Gemini CLI, GitHub Copilot, and other skill-compatible agents**\n\nCopy the skill into your agent's skills directory:\n\n```\ngit clone --depth 1 https://github.com/Eazydraft/docxtor.git /tmp/docxtor\n\nmkdir -p ~/.agents/skills\ncp -r /tmp/docxtor/plugin/skills/docxtor ~/.agents/skills/\n```\n\nGemini CLI also supports direct installation:\n\n```\ngemini skills install https://github.com/Eazydraft/docxtor.git \\\n  --path plugin/skills/docxtor\n```\n\nThe skill is self-contained and requires Node.js 20 or newer.\n\nInstall globally:\n\n```\nnpm install -g @lucio-ai/docxtor\n```\n\nOr run directly with npx:\n\n```\nnpx @lucio-ai/docxtor\n```\n\nThe `docxtor` CLI provides a structured interface for inspecting and modifying documents.\n\n```\n# Inspect a document and find a particular clause\ndocxtor view contract.docx --grep \"payment terms\"\n\n# Replace text using tracked changes\ndocxtor replace contract.docx -o redline.docx \\\n  --author \"Acme\" \\\n  --find \"within thirty (30) days\" \\\n  --replace \"within sixty (60) days\"\n\n# Add an anchored comment\ndocxtor comment contract.docx -o commented.docx \\\n  --find \"shall not exceed\" \\\n  --text \"Cap is too low.\"\n\n# Inspect existing revisions\ndocxtor revisions counterparty.docx\n\n# Resolve selected revisions\ndocxtor reject counterparty.docx -o resolved.docx \\\n  --ids 14,15 --others accept\n```\n\n| Command | Description | \n|---|---|\n| `view` | Inspect document contents, including paragraphs, tables, headers, footers, footnotes and endnotes, and inline revision markers. Supports `--grep` . | \n| `revisions` | List tracked changes with their IDs, authors, and surrounding context. | \n| `replace` | Find and replace text using native tracked changes. Only differing text is marked. | \n| `comment` | Add a Word comment anchored to a specific passage. | \n| `comments` | Inspect existing comments and their associated passages. | \n| `edit` | Apply structured JSON patches to document content. | \n| `accept` /`reject` | Resolve all revisions or selected revisions by ID or author. | \n| `metadata` | Read or modify document properties and scrub author/company information. | \n\n**Safety guarantees:**\n\n- `replace` and`edit` write tracked changes by default, attributed with`--author` . Use`--untracked` to edit directly.\n- `comment` adds a comment, attributed with`--author` ; it changes no text.\n- `accept` and`reject` resolve existing tracked changes, and`metadata` changes document properties; neither creates tracked changes.\n- Failed operations do not produce partially written output.\n- Ambiguous text matches are rejected unless the intended match is specified.\n\nSee the [CLI reference](https://github.com/Eazydraft/docxtor/blob/main/docs/cli.md) for all commands and options.\n\nWe evaluated docxtor using [docx-agent-bench](https://github.com/clauseo-ai/docx-agent-bench), a benchmark of realistic document-editing tasks involving real contracts.\n\nThe benchmark compares an AI agent equipped with the docxtor skill against the same agent without a document-editing plugin.\n\n**Evaluation setup**\n\n- 7 short tasks, 2 runs each.\n- Two models: Claude Haiku 5.5 and Claude Opus 5.5.\n- Evaluation date: November 10, 2026.\n- Benchmark commit: `e214567` .\n\nTasks covered tracked-change redlines, bulk renaming, comments, chained edits, revision resolution, multi-turn editing, and document reading.\n\nThe benchmark's document-comparison task was excluded because docxtor does not currently implement document comparison.\n\n| Model | Configuration | Grader-correct | Median time | Median tool calls | Median tool errors | \n|---|---|---|---|---|---|\n| Claude Haiku 5.5 | With docxtor | 14/14 | 17.5 s | 4 | 0 | \n| Claude Haiku 5.5 | Without plugin | 14/14 | 36 s | 7.5 | 1 | \n| Claude Opus 5.5 | With docxtor | 14/14 | 24.5 s | 5 | 0 | \n| Claude Opus 5.5 | Without plugin | 12/12 | 37 s | 6 | 0 | \n\nWith docxtor, agents completed tasks approximately **40% faster**, with zero tool errors across the evaluated runs.\n\ndocxtor is also available as a TypeScript library.\n\nApplications can use it to expose document structure to a model, receive structured editing instructions, and apply those instructions as native Word revisions.\n\nInstall:\n\n```\nnpm install @lucio-ai/docxtor\njs\nimport { Docxtor } from \"@lucio-ai/docxtor\";\n\n// Load an existing document\nconst doc = await Docxtor.load(\"contract.docx\");\n\n// Project the document into a model-readable representation\nconsole.log(doc.project(\"markdown\"));\n\n// Apply structured patches\nconst results = doc.applyPatches(\n  [\n    {\n      type: \"replace_text\",\n      target: \"p1\",\n      find: \"valid\",\n      replace: \"enforceable\"\n    },\n    {\n      type: \"insert_text\",\n      target: \"p2\",\n      position: \"after\",\n      anchor: \"terms:\",\n      text: \" and conditions:\"\n    },\n    {\n      type: \"apply_formatting\",\n      target: \"p1\",\n      find: \"enforceable\",\n      formatting: { bold: true }\n    },\n    {\n      type: \"add_comment\",\n      target: \"p1\",\n      find: \"enforceable\",\n      text: \"Confirm this wording.\"\n    }\n  ],\n  {\n    trackRevisions: true,\n    revisionAuthor: \"AI Editor\"\n  }\n);\n\n// Inspect individual patch results\nfor (const result of results) {\n  if (!result.success) {\n    console.error(`Patch failed: ${result.error}`);\n  }\n}\n\n// Export the edited document\nawait doc.toFile(\"contract-redline.docx\");\n```\n\n**Structured document representation**\n\n- Stable positional IDs for paragraphs, table cells, headers, footers, footnotes, and endnotes.\n- Access to native Word `w14:paraId` identifiers, with support for assigning them when absent.\n- Markdown and JSON projections for LLM consumption.\n- Inline formatting markers, revision markers, page breaks, and run filtering by colour.\n\n**Targeted editing**\n\n- 23 patch types covering text, paragraphs, comments, tables, rows, lists, formatting, styles, headers, and footers.\n- Fine-grained text replacement that marks only the differing text.\n- Native Word tracked changes, including `w:ins` ,`w:del` ,`w:rPrChange` , and`w:pPrChange` .\n- Accept or reject all revisions, or selectively resolve them by author or ID.\n\n**Execution guarantees**\n\n- Atomic patch batches and validation before application.\n- Structured success and failure results for individual patches.\n- All-or-nothing execution when requested.\n- Unmodified document content remains untouched.\n\n**Runtime**\n\n- Node.js 20.19 or newer.\n- ESM and CommonJS builds.\n- TypeScript declarations included.\n- Two runtime dependencies: [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) and[JSZip](https://stuk.github.io/jszip/) .\n\ndocxtor is designed around a simple principle:\n\n**Never reconstruct what you can modify in place.**\n\nTraditional document-editing approaches often convert DOCX content into an intermediate representation and regenerate the document afterward. This can introduce unintended changes to formatting, styles, relationships, and other document structures.\n\ndocxtor takes a different approach.\n\n``` php\nDOCX --> XML --> Normalized AST (read-only, with xmlRef pointers) --> LLM projection\n                        |                                                   |\n                        |                                             model produces\n                        |                                             patch objects\n                        v                                                   v\n               Mutable XML objects <-------- Patch engine (mutates via xmlRef pointers)\n                        |\n                        v\n                   Serialize --> DOCX\n```\n\nThe normalized AST is a read-only representation of the document. Each node retains an `xmlRef` pointer to its corresponding object in the parsed XML.\n\nModels operate on projections of this AST and produce structured patch objects. The patch engine resolves these patches through their references and modifies the underlying XML directly.\n\nThe AST is never serialized back into the document.\n\nThis separation allows docxtor to provide a structured, model-friendly editing interface while preserving document content and structure outside the scope of an edit.\n\n| Resource | Description | \n|---|---|\n| [CLI reference](https://github.com/Eazydraft/docxtor/blob/main/docs/cli.md) | Commands, arguments, and options | \n| [API reference](https://github.com/Eazydraft/docxtor/blob/main/docs/api.md) | Loading, creating, projecting, patching, and exporting documents | \n| [Patch types](https://github.com/Eazydraft/docxtor/blob/main/docs/patches.md) | Complete patch reference and behaviour | \n| [ID scheme](https://github.com/Eazydraft/docxtor/blob/main/docs/ids.md) | Positional IDs and native `w14:paraId` | \n| [Revision tracking](https://github.com/Eazydraft/docxtor/blob/main/docs/revisions.md) | Tracked-change generation and revision inspection | \n| [LLM integration](https://github.com/Eazydraft/docxtor/blob/main/docs/llm-integration.md) | System prompts and validate-then-apply workflows | \n| [Feature coverage](https://github.com/Eazydraft/docxtor/blob/main/docs/coverage.md) | Supported functionality and known limitations | \n| [Examples](https://github.com/Eazydraft/docxtor/blob/main/examples) | Interactive chat CLI demonstrating model-driven editing | \n\nThe following are not currently supported:\n\n- Merged cells.\n- Images.\n- Creating new styles.\n- Reading existing comments through the library API (the CLI supports listing comments).\n- Document comparison.\n- Mathematical equations.\n\nSee [feature coverage](https://github.com/Eazydraft/docxtor/blob/main/docs/coverage.md) for the complete breakdown.\n\nContributions are welcome.\n\nSee [CONTRIBUTING.md](https://github.com/Eazydraft/docxtor/blob/main/CONTRIBUTING.md) for development setup, architectural invariants, and contribution requirements.\n\nThe CLI source lives in [`cli/`](https://github.com/Eazydraft/docxtor/blob/main/cli).\n\n```\n# Build the npm package\npnpm build\n\n# Rebuild the self-contained agent skill\npnpm build:skill\n```\n\nEvery commit requires DCO sign-off.\n\ndocxtor is released under the [MIT License](https://github.com/Eazydraft/docxtor/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees", "canonical_source": "https://github.com/Eazydraft/docxtor", "published_at": "2026-11-11 11:58:36+00:00", "updated_at": "2026-11-11 12:21:59.480468+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["docxtor", "Eazydraft", "@lucio-ai/docxtor", "Claude Cowork", "Claude.ai", "Codex", "Cursor", "Gemini CLI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees", "markdown": "https://wpnews.pro/news/show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees.md", "text": "https://wpnews.pro/news/show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees.txt", "jsonld": "https://wpnews.pro/news/show-hn-a-docx-editing-library-inspired-by-rosyln-s-syntax-trees.jsonld"}}