docx-cli

docx-cli

A .docx CLI built for AI agents. Leave comments, suggest redlines, and edit Word documents without breaking the formatting or losing content — a human accepts or rejects in Word afterward.

• Hand a .docx to Claude or Codex and get back a redlined copy with comments — open it in Word, accept or reject as usual.
• Agents address text by stable locators with character offsets (p3:5-20); humans see normal Word formatting on disk.
• Custom styles, theme colors, embedded objects — all of it survives. The CLI mutates XML in place rather than re-emitting from a lossy model.

Why docx-cli?

The default way agents edit Word docs is to unzip the .docx and hand-write the OOXML inside. That takes a strong model to get right, burns tokens, and routinely produces a file Word won't open. docx-cli hands the agent plain commands plus an annotated-Markdown read view, so it never has to reason about the XML.

We measured it — a controlled A/B bake-off: six real document tasks (fill an NDA, fill an invoice, restyle a résumé, redline a contract, finalize a contract, author a journal), the same starting files, and one independent judge grading every result from the Word-rendered pages. Three runs per arm at each of two model tiers. Haiku columns: July 2026 rerun on v0.20.4; Sonnet columns: June 2026 bake-off (not Sonnet 5):

	Haiku (weak, cheap)		Sonnet (strong, June run — not Sonnet 5)
	docx-cli	default skill	docx-cli	default skill
Tasks solved (of 6)	5.0 (5–5)	0.7 (0–2)	6.0 (6–6)	4.0 (4–4)
Rendered correctly (of 6)	6.0	4.3	6.0	4.7
Outright-broken documents	0	~1.3/run (up to 2)	0	0
Effective input tokens	3.2M	7.9M (2.5×)	1.6M	3.6M (2.2×)
Output tokens	78k	155k (2.0×)	—	—
Wall-clock	1,186 s	2,438 s (2.1× slower)	1,175 s	2,029 s (1.7× slower)

• The correctness gap is widest on the cheap Haiku tier (~7×), and a frontier model never closes it — the default skill caps at 4/6, losing the contract redline and the résumé every Sonnet run.
• The cost and speed penalties are model-independent — ~2.2–2.5× more input tokens and ~1.7–2.1× slower at both tiers, with token/time ranges that never overlap. (Output tokens, measured in the July rerun: 2× more for the default skill. The June Sonnet run measured input only.)
• Word couldn't reliably open the default skill's work — in the July Haiku runs it failed to open 4 of the skill's 18 outputs (both legal-redline deliverables in 2 of 3 runs); all 18 of docx-cli's opened on the first try.

Full methodology, per-task rubrics, and the harness that produced these numbers: .claude/skills/weak-agent-test.

Install

npm — the simplest path (requires Bun >= 1.3):

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

Standalone binary (no Bun required). Every release publishes prebuilt binaries plus a SHA256SUMS manifest, and the installer verifies the binary's SHA-256 before installing:

curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh

Honors PREFIX (default $HOME/.local/bin) and VERSION (default latest). Pre-built for linux/x64, linux/arm64, darwin/x64, darwin/arm64, windows/x64. Prefer to inspect first? Download docx-<platform> + SHA256SUMS from the latest release, verify, chmod +x, and put it on PATH.

Quick example: filling out an NDA

The repo includes a Common Paper Mutual NDA template at tests/fixtures/mnda.docx. Below are the primitives an agent would compose to fill in the cover page and leave redline edits — the same flow shown in the video above. Every command was verified end-to-end against the fixture:

# Make a copy first — there's no undo (git is the history; the CLI overwrites in place)
cp tests/fixtures/mnda.docx mnda-filled.docx