docx-cli

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.