Edit and redline Word documents with AI agents

docx-cli

Let your AI agent do real work in your Word documents. Fill in contracts and forms, update tables and figures, restyle a résumé, write a report from scratch, or review a draft with tracked changes and comments. When you open the file in Word, it still looks like yours.

• Let your agents cheaply work at a fraction of the cost and time of most skills. Official skills force agents to unpack and self-manage OOXML that composes Word documents, which means that basic operations can be quite expensive on tokens and time. CLIs like OfficeCLi often force them to compose smaller operations with JSON they often struggle to understand in context. docx-cli makes the work familiar by standardizing most operations as creating, updating, deleting, or replacing Markdown.
• Use less-capable models. docx-cli is tuned to work even if the model is weak (like Haiku, Luna, or even Qwen 3.5 9B). It decreases context use by using a Markdown that survives multiple rounds of insertions and updates instead of JSON. It also saves on context by avoiding reading images of the documents by including as much visual context as annotations. It self-documents by providing clear help text with examples, but also providing actionable hints when something goes wrong.
• Built from the ground up for review workflows. It's built to handle change tracking, accept/reject changes, and handle interactions from multiple reviewers.
• Works with any harness. Works with Claude Code, Codex, Pi, and anything else that reads the open Agent Skills format.

How it benchmarks

In short: on our six-task benchmark, docx-cli got the same results as Anthropic's docx skill (the skill Claude uses for Word files) in 27% less time, with 22% fewer input tokens and 41% fewer output tokens using Haiku 5.5. Compared to OfficeCLI, it was roughly 2x faster at half of the tokens, while finishing every task that OfficeCLI got wrong.

• Editing existing documents is where docx-cli saves. On the five editing tasks it used about 30% fewer input tokens and 35% less time than Anthropic's skill.
• On the two contract tasks, all three tools passed every run. There the difference is cost and speed, not correctness.
• OfficeCLI's four misses were the résumé every time (after the margin change, every date line wrapped, some mid-word, e.g. "Cambrid / ge, MA") and one invoice (the old notes line was left in place). That résumé wrap is a trap docx-cli specifically repairs, so read "fewer misses" with that in mind.
• Every output from every tool opened in Word.

What to know about this benchmark. We wrote docx-cli, the six tasks, and the grading rubrics, and these tasks are also the regression suite docx-cli is developed against. It's three runs per tool on one model. The judge knew which tool produced each result; competitor runs carried an instruction to grade the rendered pages and not penalize a different internal approach. Competitors were pinned (Anthropic skill at anthropics/skills@dbd4588, OfficeCLI 1.0.156 by SHA-256). On older models the correctness gap was large (Haiku 4.5, July 2026: 5.0/6 vs 0.7/6 for the default skill); on current models it has closed. Per-task numbers, every caveat, and how to reproduce: benchmarks/2026-10-10.

Agent Setup

Paste this messages into your agent of choice:

Set up docx-cli (https://github.com/kklimuk/docx-cli) so you can edit Word documents for me.
1. Install the skill for the agent you are:
   - Claude Code: claude plugin marketplace add kklimuk/docx-cli && claude plugin install docx-cli@docx-cli
   - Codex: codex plugin marketplace add kklimuk/docx-cli   (the skill loads automatically; nothing else to install)
   - Any other agent: npx skills add kklimuk/docx-cli -g -y
2. Install the `docx` program:
   - If Bun is installed: bun add -g bun-docx
   - Otherwise, from an empty temporary directory:
       curl -fsSLO https://github.com/kklimuk/docx-cli/releases/latest/download/install.sh
       curl -fsSLO https://github.com/kklimuk/docx-cli/releases/latest/download/SHA256SUMS
       shasum -a 256 -c SHA256SUMS --ignore-missing   (or: sha256sum -c SHA256SUMS --ignore-missing)
     Only if that prints "install.sh: OK", run: REQUIRE_CHECKSUM=1 sh install.sh
   - Windows: download docx-windows-x64.exe from https://github.com/kklimuk/docx-cli/releases/latest,
     compare `Get-FileHash docx-windows-x64.exe` with its line in SHA256SUMS, rename it to docx.exe,
     and put it on PATH.
3. Run `docx --version`. If it isn't found, add ~/.local/bin to PATH and try again.
4. Tell me it's ready. (In Claude Code, the skill is available from the next session.)
Note: the npm package is `bun-docx`. The npm packages named `docx` and `docx-cli` are unrelated.

Or install the skill yourself

Any agent (skills.sh):

npx skills add kklimuk/docx-cli

Claude Code:

/plugin marketplace add kklimuk/docx-cli
/plugin install docx-cli@docx-cli

Codex (the plugin's skills auto-discover):

codex plugin marketplace add kklimuk/docx-cli

Pi (the pi manifest in package.json pulls in the skill), then invoke /skill:docx-cli:

pi install git:github.com/kklimuk/docx-cli      # global; add -l for a project (team-shared) install

Manual: copy skills/docx-cli/ into your agent's skills directory (e.g. ~/.claude/skills/ or the cross-tool ~/.agents/skills/). If docx isn't installed, the skill tells the agent to run scripts/bootstrap.sh, which installs a pinned, checksum-verified binary (and, run again later, updates one that's behind).

The skill is thin on purpose: it teaches the workflows, then defers to docx <command> --help, which ships with the program, so it can't go stale. docx info skill prints the canonical SKILL.md for the installed version.

Why docx-cli instead of something else?

On our benchmark docx-cli solved every task and was the cheapest and fastest of the three tools above. Here's how it compares with each alternative.

• Anthropic's docx skill: docx-cli has the same accuracy, with less spend. docx-cli took 27% less time, 22% fewer input tokens, 41% fewer output tokens, and 98 tool calls against 124. On finalizing a redline it used about half: 94k tokens and 86 s against 179k and 159 s. The skill has the agent hand-edit Word's XML with helper scripts; docx-cli gives it commands such as track-changes apply --accept rev1 --reject rev0. It's one program instead of Python, Node, pandoc, and LibreOffice, and it's MIT-licensed, while the skill's license limits it to Anthropic's services; docx-cli runs under Codex or any other agent. The skill was cheaper on our one from-scratch document, so if you mostly write new documents with Claude, it's a reasonable choice.
• OfficeCLI: docx-cli solves more tasks, at half the cost. On our Word tasks docx-cli solved 6 of 6 against 4.7, with about half the tokens and time (most of OfficeCLI's misses were a résumé layout trap docx-cli was built to repair).
• Claude for Word and Copilot: docx-cli needs no Word to make progress. In-Word assistants work on one open document while a person drives. docx-cli lets the agent work on the files directly: a folder of contracts, a scheduled job, an agent like Claude Code or Codex. If you'd rather sit in Word and steer, Claude for Word does tracked changes too.
• python-docx, Open XML SDK, or generate-and-compare: docx-cli doesn't write throwaway code. With a library the agent writes new code for every document, handles text Word splits across runs, and, with python-docx, gets no API for tracked changes. Generating a new copy and running Word's Compare gives a redline shaped by the diff, and the regenerated copy's formatting can drift. docx-cli tracks each change as it's made, scoped to the phrase.
• pandoc: docx-cli can edit instead of regenerating. pandoc is excellent at Markdown to Word (docx-cli's create --from draft.md does that too), but editing an existing file means regenerating it from Markdown, which drops what Markdown can't hold. On our test fixtures (tests/fixtures/text-boxes.docx and sections.docx), pandoc in.docx -o in.md && pandoc in.md --reference-doc=in.docx -o out.docx lost a text box along with its text and merged eight sections, with their columns, into one.

What docx-cli doesn't do: MCP.

Is it safe to use on real documents?

Yes.

• Your document stays on your machine. No command sends content anywhere. The only network access is installing or upgrading the program, plus images add when you give it a web address. See SECURITY.md.
• Every edit can be reviewed. Ask the agent to turn tracking on, so each change is a Word tracked change you can reject one by one.
• Edits are surgical. docx-cli changes only what it was asked to change; everything else in the file, including parts of Word's format it doesn't understand, passes through untouched. It never deletes something the document still points to.
• Work on a copy. docx-cli saves changes into the file it's given, so ask the agent to save to a new file (-o) or keep the original. --dry-run previews a change without saving it, and docx diff FILE --against ORIGINAL.docx lists what changed as text (it isn't a Word compare).

For developers

Install the program yourself

npm. The package is bun-docx, and it runs under Bun ≥ 1.3 even when installed with npm. If you're embedding docx-cli in a Node or Python service, use the standalone binary instead.

bun add -g bun-docx        # or: npm install -g bun-docx
bunx bun-docx read doc.docx   # run without installing

Every command works directly on the .docx file. Only docx render (page images, for checking layout) needs Word (macOS/Windows) or LibreOffice installed.

Upgrading: docx upgrade replaces a standalone binary in place, using the installer embedded in the binary at build time (never fetched), pinned to a release tag and SHA-256-verified. docx upgrade --to v0.27.0 pins a version; --dry-run reports what would change. It won't touch an npm install (use your package manager) or a renamed binary. On Windows it needs Git Bash (for sh); a running .exe can be renamed but not overwritten, so the verified binary is swapped in and the old one is left as docx.exe.old until the next upgrade.

Use it from your own code

docx-cli is a command-line program with a machine-friendly contract, so any language can call it as a subprocess:

• The exit code is the success signal: 0 ok, 1 general failure, 2 usage error, 3 not found. A replace or comments add --anchor that matches nothing exits 3 instead of reporting success. replace changes the first match unless you pass --all; any further matches are reported, not treated as an error.
• Errors are JSON on stdout: {"code":"MATCH_NOT_FOUND","error":"…","hint":"…"}, so capture stdout on failure too (in Python, json.loads(error.stdout)["code"] on a CalledProcessError with capture_output=True).
• Structured output: docx read FILE prints annotated Markdown with locator comments; --ast prints the lossless JSON tree; most list verbs print JSON (track-changes list prints a table unless you add --json); --verbose gives a JSON acknowledgement on every change.
• Stable addresses: paragraphs, tables, cells, comments, and tracked changes all have locators (p3, p3:5-20, t0:r1c2, c0, rev1). docx find FILE "phrase" returns the exact span.
• Batches: edit, insert, replace, delete, and the comments verbs take --batch FILE.jsonl (- for stdin). Every locator in a batch addresses the document as you read it.
• No MCP server. Agents call docx through their shell tool with the bundled skill, which is the setup benchmarked above.
• Pre-1.0. Flags can still change between minor versions. Pin a version in production.

import json, os, subprocess
env = {**os.environ, "DOCX_AUTHOR": "Acme Legal"}   # the name on every tracked change
subprocess.run(["docx", "track-changes", "on", "contract.docx"], check=True, env=env)
subprocess.run(["docx", "replace", "contract.docx", "Net 90", "Net 30", "--all"], check=True, env=env)
changes = json.loads(subprocess.run(
    ["docx", "track-changes", "list", "contract.docx", "--json"],
    check=True, capture_output=True, text=True).stdout)

Tested on every commit: about 1,900 unit tests, a LibreOffice round-trip of every fixture, and schema checks against the ECMA-376 XSDs (docx validate runs the same check on any file).

For IT administrators

• Data: fully local, no telemetry. Network access happens only when someone installs or upgrades the program, or passes a web address to images add.
• Nothing updates in the background. The binary changes only when someone runs docx upgrade, the installer, or the skill's bootstrap.sh (which installs docx when it's missing and updates one that's behind). Pin a fleet with DOCX_CLI_VERSION=v0.27.0 in the agent's environment, plus VERSION= / docx upgrade --to for the install itself.
• Air-gapped installs, the network endpoints to allow, Windows and macOS signing, and maintainer risk: see SECURITY.md → Deploying in an organization.

Learn more

• docx --help and docx <command> --help: the authoritative, versioned contract. Agents should start here.
• REFERENCE.md: every command, the output contract, the locator grammar, common workflows, and how it works under the hood.
• SECURITY.md: install integrity, data handling, deployment, and reporting vulnerabilities.
• CONTRIBUTING.md: development setup, architecture, the stack, and CI.