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 (weak, cheap) Sonnet (strong) docx-cli default skill docx-cli default skill Tasks solved (of 6) 4.3 (4–5) 0.7 (0–1) 6.0 (6–6) 4.0 (4–4) Rendered correctly (of 6) 6 3.7 6.0 4.7 Outright-broken documents 0 ~1/run (up to 2) 0 0 Input tokens 2.4M 6.1M (2.6×) 1.6M 3.6M (2.2×) Wall-clock 924 s 1,882 s (2.0× slower) 1,175 s 2,029 s (1.7× slower) The correctness gap is widest on the cheap Haiku tier (~6×) , 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.6× more tokens and ~1.7–2× slower at both tiers, with token/time ranges that never overlap. Word couldn't reliably open the default skill's work — it failed to open 5 of 36 of its outputs; all 36 of docx-cli's opened on the first try. Full methodology, per-task rubric, and side-by-side renders: the bake-off writeup . 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 # Read the cover-page table so the agent knows what placeholders exist docx read mnda-filled.docx --from t1 --to t1 # Fill the yellow-highlighted bracketed placeholders docx replace mnda-filled.docx " Fill in: today's date " " May 6, 2026 " docx replace mnda-filled.docx " fill in state and/or county " " California " docx replace mnda-filled.docx " fill in state " " California " docx replace mnda-filled.docx " Fill in, if any. " " None. " # Verify nothing's left to fill (bare locator lines, one per match; nothing → exit 0) docx find mnda-filled.docx ' \[(Fill|fill)[^]]*\] ' --regex --all # Flip on tracked changes for the redline pass docx track-changes mnda-filled.docx on # Tighten "having a reasonable need to know" in the Use & Protection clause docx replace mnda-filled.docx \ " having a reasonable need to know " \ " with a documented need to know " # Leave a comment for the human reviewer — addresses an existing span with --at docx comments add mnda-filled.docx --at p7:0-30 \ --text " Should we narrow 'representatives' to a named list? " Open mnda-filled.docx in Word: tracked changes and comments appear in the review pane, ready to accept, reject, or reply. Or run docx track-changes accept mnda-filled.docx --all to bake them in from the CLI. Use as an agent skill docx-cli ships as an Agent Skill — one SKILL.md that works across Claude Code, Codex, Pi, and the other harnesses that read the open skill format. The skill teaches the locator model and the redline / comment / fill workflows, then defers to docx <command> --help at runtime, so it can't go stale. Why a skill? docx-cli is built for the weakest, cheapest agents. In our weak-agent benchmark — 6 real document tasks (fill a contract, redline, comment, restyle, author from scratch), graded against Word renders, 3 runs each — Haiku driving docx-cli completed 4.3/6 tasks versus 0.7/6 for the default Claude skill, at roughly 2.5× fewer tokens ; with Sonnet it's 6/6 vs 4/6 , with roughly 2x fewer tokens. And every docx-cli output opened cleanly in Word on the first try — it never emits a file the renderer rejects. (Methodology and harness: .claude/skills/weak-agent-test .) Install Any agent ( skills.sh ) — one cross-harness command, installs into whichever agent you're using: npx skills add kklimuk/docx-cli Claude Code — one-line plugin install: /plugin marketplace add kklimuk/docx-cli /plugin install docx-cli@docx-cli Codex — add the marketplace (the plugin's skills auto-discover): codex plugin marketplace add kklimuk/docx-cli Pi — one-command install (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 alternative: pi --skill /path/to/docx-cli/skills/docx-cli Any harness / manual — drop skills/docx-cli/ into your agent's skills directory (e.g. ~/.claude/skills/ or the cross-tool ~/.agents/skills/ ). On first activation the skill's scripts/bootstrap.sh installs the docx binary (and self-updates a stale one). Keeping the skill current The binary is the source of truth: docx info skill prints the canonical SKILL.md for the installed version, and a CI test fails if the committed copy drifts. Regenerate after any change with: docx info skill > skills/docx-cli/SKILL.md docx <command> --help is the authoritative contract Agents: run docx <command> --help before composing a call. Every command's --help is the source of truth for its flags, locator forms, and exact output shape — this README is a map, not the territory. Two more must-reads: docx info locators — the canonical locator grammar ( --json for a machine-readable form). The top-level docx --help says it outright: "It is highly recommended to agents to run docx info locators to understand their capabilities." docx info schema — the AST type definitions ( --ts for TypeScript source) that read --ast emits. Command reference docx <verb> and docx <noun> <verb> . Every command has --help . Two groups: read/query commands print data to stdout; mutate commands change the file (and accept --dry-run , -o/--output PATH , -v/--verbose ). Read & query (print to stdout, never write the file) docx read FILE [--from LOC] [--to LOC] [--accepted | --baseline | --current] [--comments] docx read FILE --ast # JSON-AST instead of Markdown (disables the markdown-only flags) docx find FILE QUERY [--regex] [--ignore-case] [--all] [--nth N] [--current | --baseline] [--exact] [--json] docx find FILE (--highlight COLOR | any | --color HEX | --bold | --italic | --underline) [--all] [--json] # find by formatting (no QUERY) docx wc FILE [LOCATOR] [--accepted | --baseline | --current] [--json] docx outline FILE [--style-prefix S] [--json] d