Show HN: Docx-CLI: エージェントがWord文書を半分の時間とトークンで読み書き
Show HN: Docx-CLI: agents read/edit Word docs using 1/2 the time and tokens (github.com)
要約
Docx-CLIは、AIエージェントがWord文書(.docx)を効率的に読み書きするためのコマンドラインインターフェースです。フォーマットを維持しつつ、コメントの追加、変更提案(redlines)、編集を可能にし、人間がWordで最終確認できます。AIがOOXMLを直接操作する代わりに、構造化されたコマンドとMarkdownビューを使用するため、トークン消費が少なく、Wordで開けないファイルが生成されるリスクが低減されます。
全文翻訳
docx-cli
AIエージェントにWord文書での実際の作業を任せましょう。 契約書やフォームへの記入、表や図の更新、履歴書のスタイル変更、ゼロからのレポート作成、変更履歴やコメント付きのドラフトレビューなどを行います。Wordでファイルを開いたとき、それはあなたのファイルのように見えます。
[画像: Release] [画像: CI] [画像: npm] [画像: License: MIT]
[画像: Watch: ClaudeがNDAに記入し、赤入れする様子]
- エージェントに、ほとんどのスキルよりもはるかに低コストと短時間で作業させましょう。 公式スキルはエージェントにWord文書を構成するOOXMLを展開・自己管理させるため、基本的な操作はトークンと時間に関して非常に高価になる可能性があります。OfficeCLiのようなCLIは、JSONでより小さな操作を構成させることが多いですが、エージェントはコンテキストを理解するのに苦労することがよくあります。
docx-cliは、ほとんどの操作をMarkdownの作成、更新、削除、置換として標準化することで、作業を馴染み深いものにします。 - 能力の低いモデルを使用できます。 docx-cliは、Haiku、Luna、あるいはQwen 3.5 9Bのような弱いモデルでも動作するように調整されています。JSONの代わりに複数の挿入および更新ラウンドに耐えるMarkdownを使用することで、コンテキストの使用量を減らします。また、視覚的なコンテキストを注釈としてできるだけ多く含めることで、文書の画像を読み取ることを避けてコンテキストを節約します。明確なヘルプテキストと例を提供することで自己文書化されますが、問題が発生した際には実行可能なヒントも提供します。
- レビューワークフローのためにゼロから構築されています。 変更履歴の追跡、変更の承諾/拒否、複数のレビュー担当者からのインタラクションを処理できるように構築されています。
- あらゆるハーネスで動作します。 Claude Code、Codex、Pi、およびオープンなAgent Skills形式を読み取るその他のもので動作します。
ベンチマーク結果
要するに: 6つのタスクのベンチマークで、docx-cliはHaiku 5.5を使用して、Anthropicのdocxスキル(ClaudeがWordファイルに使用するスキル)と同じ結果を、27%短い時間、22%少ない入力トークン、41%少ない出力トークンで達成しました。OfficeCLIと比較して、トークン数は半分で約2倍速く、OfficeCLIが間違えたすべてのタスクを完了しました。
| Haiku 5.5 | docx-cli 0.27.0 | Anthropic docx skill | OfficeCLI 1.0.156 |
|---|---|---|---|
| 解決したタスク数(6件中) | 6.0 | 6.0 | 4.7 |
| 全ての実行で解決(全3回) | 6/6 | 6/6 | 4/6 |
| 入力トークン(キャッシュ加重) | 902k | 1.15M (+27%) | 1.92M (+113%) |
| 出力トークン | 32k | 54k (+70%) | 63k (+97%) |
| 全6タスクの壁時計時間 | 914 s | 1,254 s (+37%) | 1,834 s (+101%) |
| ツール呼び出し | 98 | 124 (+26%) | 165 (+69%) |
- 既存文書の編集でdocx-cliは節約になります。 5つの編集タスクでは、Anthropicのスキルよりも入力トークンが約30%少なく、時間も35%短縮されました。
- 2つの契約タスクでは、3つのツールすべてがすべての実行で合格しました。 そこでは、コストと速度の違いであり、正確さではありません。
- OfficeCLIの4つのミスは、毎回履歴書でした(マージン変更後、すべての日付行が折り返され、一部は単語の途中で折り返されました。例:「Cambrid / ge, MA」)。また、請求書(古い注釈行がそのまま残っていました)も1件ありました。その履歴書の折り返しは、docx-cliが特別に修正するトラップなので、「ミスが少ない」という点を念頭に置いてください。
- すべてのツールのすべての出力はWordで開かれました。
このベンチマークについて知っておくべきこと。 docx-cli、6つのタスク、および採点基準は私たちが作成しました。これらのタスクは、docx-cliが開発されている回帰テストスイートでもあります。これは、1つのモデルでツールごとに3回の実行です。審査員はどのツールがどの結果を生成したかを知っていました。競合他社の実行には、レンダリングされたページを採点し、異なる内部アプローチを罰しないようにという指示がありました。競合他社は固定されました(Anthropicスキルはanthropics/skills@dbd4588、OfficeCLIはSHA-256による1.0.156)。古いモデルでは正確性のギャップが大きかった(Haiku 4.5、2026年7月:デフォルトスキルで5.0/6対0.7/6)ですが、現在のモデルでは閉じました。タスクごとの数値、すべての注意点、および再現方法については、benchmarks/2026-10-10を参照してください。
エージェント設定
以下のメッセージを、選択したエージェントに貼り付けてください。
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.
または自分でスキルをインストールする
あらゆるエージェント (skills.sh):
npx skills add kklimuk/docx-cli
Claude Code:
/plugin marketplace add kklimuk/docx-cli
/plugin install docx-cli@docx-cli
Codex(プラグインのスキルは自動検出されます):
codex plugin marketplace add kklimuk/docx-cli
Pi(package.jsonのpiマニフェストがスキルをプルします)、次に/skill:docx-cliを呼び出します:
pi install git:github.com/kklimuk/docx-cli # global; add -l for a project (team-shared) install
手動: skills/docx-cli/ をエージェントのスキルディレクトリ(例:~/.claude/skills/またはクロスツール~/.agents/skills/)にコピーします。docxがインストールされていない場合、スキルはエージェントにscripts/bootstrap.shを実行するように指示します。これは、ピン留めされた、チェックサム検証済みのバイナリをインストールします(再度実行すると、古いものを更新します)。
スキルは意図的に薄く作られています。ワークフローを教え、その後docx <command> --helpに委ねます。これはプログラムに付属しており、古くなることはありません。docx info skillは、インストールされているバージョンの正規のSKILL.mdを表示します。
なぜdocx-cliなのか?
私たちのベンチマークでは、docx-cliはすべてのタスクを解決し、3つのツールのうち最も安価で最速でした上記。以下に各代替手段との比較を示します。
- Anthropicのdocxスキル:docx-cliは同じ精度で、より少ない支出です。 docx-cliは、時間で27%少なく、入力トークンで22%少なく、出力トークンで41%少なく、ツール呼び出しは124件に対して98件でした。赤入れの最終処理では、約半分を使用しました:179kトークンと159秒に対して94kトークンと86秒です。このスキルは、エージェントがヘルパースクリプトを使用してWordのXMLを手動で編集しますが、docx-cliは
track-changes apply --accept rev1 --reject rev0のようなコマンドを提供します。これはPython、Node、pandoc、LibreOfficeの代わりに1つのプログラムであり、MITライセンスです。一方、スキルのライセンスはAnthropicのサービスに限定されています。docx-cliはCodexまたはその他のエージェントで実行できます。スキルは、ゼロから作成した文書ではより安価でした。したがって、Claudeで新しい文書を主に作成する場合は、合理的な選択肢です。 - OfficeCLI:docx-cliはより多くのタスクを、半分のコストで解決します。 Wordタスクでは、docx-cliは6件中6件を解決し、OfficeCLIの4.7件に対して約半分のトークンと時間でした(OfficeCLIのミスのほとんどは、docx-cliが修正するために構築された履歴書のレイアウトのトラップでした)。
- Claude for WordとCopilot:docx-cliは進歩するためにWordを必要としません。 Word内のアシスタントは、人が操作している間に1つの開いている文書で作業します。docx-cliは、エージェントがファイルに直接(契約書のフォルダ、スケジュールされたジョブ、Claude CodeやCodexのようなエージェント)作業できるようにします。Word内で操作を指示したい場合は、Claude for Wordも変更履歴を追跡します。
- python-docx、Open XML SDK、またはgenerate-and-compare:docx-cliは使い捨てのコードを書きません。 ライブラリを使用すると、エージェントは文書ごとに新しいコードを書き、Wordが実行をまたいで分割するテキストを処理し、python-docxでは変更履歴のAPIが提供されません。新しいコピーを生成し、WordのCompareを実行すると、差分によって形成された赤入れが得られ、再生成されたコピーのフォーマットがずれる可能性があります。docx-cliは、変更が行われるたびに、フレーズにスコープされた各変更を追跡します。
- pandoc:docx-cliは再生成ではなく編集できます。 pandocはMarkdownからWordへの変換(docx-cliの
create --from draft.mdも同様)に優れていますが、既存のファイルを編集するにはMarkdownから再生成する必要があり、Markdownで保持できないものは失われます。テストフィクスチャ(tests/fixtures/text-boxes.docxおよびsections.docx)では、pandoc in.docx -o in.md && pandoc in.md --reference-doc=in.docx -o out.docxはテキストボックスとそのテキストを失い、8つのセクションを列とともに1つにマージしました。
docx-cliができないこと: MCP。
本物の文書に使用しても安全ですか?
はい。
- 文書はローカルマシンに残ります。 コマンドはいかなる内容もどこにも送信しません。ネットワークアクセスは、プログラムのインストールまたはアップグレード、および
images addでWebアドレスを指定した場合のみ発生します。SECURITY.mdを参照してください。 - すべての編集はレビュー可能です。 エージェントに変更履歴の追跡をオンにするように依頼すると、各変更はWordの変更履歴として記録され、1つずつ拒否できます。
- 編集は外科的です。 docx-cliは要求されたものだけを変更します。ファイル内の他のすべての部分(Wordが理解しないフォーマットの一部を含む)は変更されずに通過します。文書がまだ参照しているものを削除することはありません。
- コピーで作業してください。 docx-cliは変更を渡されたファイルに保存するため、エージェントに新しいファイル(
-o)に保存するか、元のファイルを保持するように依頼してください。--dry-runは保存せずに変更をプレビューし、docx diff FILE --against ORIGINAL.docxは変更された内容をテキストとして一覧表示します(Wordの比較ではありません)。
開発者向け
プログラムを自分でインストールする
npm。 パッケージはbun-docxで、npmでインストールした場合でもBun ≥ 1.3で実行されます。NodeまたはPythonサービスにdocx-cliを組み込む場合は、代わりにスタンドアロンバイナリを使用してください。
bun add -g bun-docx # または: npm install -g bun-docx
bunx bun-docx read doc.docx # インストールせずに実行
すべてのコマンドは.docxファイルに直接作用します。docx render(レイアウト確認用のページ画像)のみがWord(macOS/Windows)またはLibreOfficeを必要とします。
アップグレード: docx upgradeは、ビルド時に埋め込まれたインストーラー(取得されることはない)を使用して、リリースタグとSHA-256検証済みのスタンドアロンバイナリをインプレースで置き換えます。docx upgrade --to v0.27.0はバージョンをピン留めします。--dry-runは変更される内容を報告します。npmインストール(パッケージマネージャーを使用)、名前変更されたバイナリ、または実行中の.exeを置き換えられないWindows(手動で新しいものをダウンロードする必要がある)には影響しません。
独自のコードから使用する
docx-cliはマシンフレンドリーな契約を持つコマンドラインプログラムなので、どの言語からでもサブプロセスとして呼び出すことができます。
- 終了コードが成功のシグナルです:
0OK、1一般的な失敗、2使用法エラー、3見つかりません。replaceまたはcomments add --anchorが一致しない場合、成功を報告する代わりに3で終了します。replaceは、--allを渡さない限り、最初の一致を変更します。それ以降の一致はエラーとしてではなく、報告されます。 - エラーは標準出力にJSONで出力されます: `{