4 ms·
Show HN: Docx-CLI: agents read/edit Word docs using 1/2 the time and tokens
- kirillklimuk 4mo agoI originally started this project just to build a TA agent for a professor who didn't have any TAs (my wife). So as you can imagine, it was critical that it could properly write comments and only edit with track edits mode on... and do all of this without accidentally breaking the structure of the doc that couldn't be read. It's since then expanded to cover everything from editing tables, hyperlinks, footnotes, and a lot more. Now it's a pretty powerful tool that can trivially fill out a MNDA form, mark up a contract, author a poetry booklet, and fill out an invoice, which is now the eval suite where the numbers in the title come from. You might be asking, "why did you do all of this?" Well, I'm building an agent harness for normies that are not gonna know what a token even is but just want their stuff not to take an epoch and a half to run. So I've got to make the tools be MUCH more optimal than they've even been. I figure putting them out to the community and inviting all of you to help me might be a way to do that =).
- kxjxudisjsn 4mo ago[dead]
- firasd 4mo agoVery cool. So much of the 'capability overhang' of AI can be addressed with tools like this--data manipulation etc without LLMs having to galaxy brain everything in token space
- kirillklimuk 4mo agoYeah, I agree. Working on something like this for PDFs.
- MoAz06 4mo agoI like it
- rubyfan 4mo agoI haven’t looked under the hood here but to make simple text replacement via command line is an LLM even required? A human driven command line tool to do basic substitution on batches of files reliably would be amazing.
- BorisMelnik 4mo agothere is a python library for docx handling. my thinking was the use case for this was for larger scale automations / document processing.
- asdff 4mo agosed, awk. docx is just zipped xml.
- phil-martin 4mo agoIt is just zipped xml, but to do a search and replace while retaining document structure is very very complicated, and I’m struggling to think of how to combine sed and awk to achieve it.
- cyanydeez 4mo agoyou've never dealt with ooxml.
- rubyfan 4mo agoSadly I have spent lots of time with ooxml and pdf and my experience suggests there really aren’t reliable means for dealing with seemingly simple changes.
- kirillklimuk 4mo agoNot really - if you wanna do a text replacement you can extract it yourself and do some work (or just use this CLI). The library is designed for longer workloads.
- simlevesque 4mo agoI've done many custom low token output CLIs like this for my day job and it's something I expect to see much more of.
- DenisM 4mo agoHow would you compare that approach to spawning sub agents to operate high-token tools?
- kirillklimuk 4mo agoIf your goal is to use less overall tokens to solving a task, then spawning subagents is not the best idea. Generally, they will have to use more tokens to reach the same outcome, per some research: https://arxiv.org/abs/2604.02460 https://arxiv.org/abs/2604.02460
- topaztee 4mo agonice to see others try to solve a problem we also experienced. I'm also working on letting agents read/edit word docs but exposing it as a simple MCP www.vespper.com
- kirillklimuk 4mo agoThat's pretty cool!
- danielsmori 4mo agoNice — CLI-first for document tooling is underrated. How are you handling embedded images in the XML? That was a pain point when I was parsing OOXML in a different context.
- kirillklimuk 4mo agoIf the reader needs the images, there's an explicit extract command that gets them into a folder. If the writer needs to update them, there's and explicit replace command and insert commands for that purpose. It all has to go into the relationship files of course.
- ryuji_yasu 4mo ago[flagged]
- felooboolooomba 4mo agoI know that the office suite format is a relic which is hard to get rid of. But I can't help feeling that in these new AI era, that we should focus on leaving that proprietary format behind. It is one of the biggest facilitator of vendor lock in in the history of computing.
- FailMore 4mo agoHey, I'm building something a bit like that - please checkout https://smalldocs.org https://smalldocs.org if you have time. I say it’s as if “Claude Code & Microsoft Office had a baby...” Code available: https://github.com/espressoplease/smalldocs https://github.com/espressoplease/smalldocs Discord: https://discord.gg/txjATTsDaq https://discord.gg/txjATTsDaq Sample document: https://smalldocs.org/blogs/what-is-a-smalldoc https://smalldocs.org/blogs/what-is-a-smalldoc Invoked via Claude Code by saying stuff like: “sdoc me the plan for this feature”, or “dig into our logs and sdoc me a report on our latency"
- kirillklimuk 4mo agoRealistically... everyone's using it from students, to lawyers, to academics, and so on and so forth. And given that LibreOffice and Google Docs are pretty good nowadays and OOXML is an open standard now post the monopoly rulings of the 90s, it's not quite as bad as it used to be.
- gawkdev 4mo ago[dead]
- librasteve 4mo agothis is awesome - I wonder how this would combine with DSL tools like https://slangify.org https://slangify.org
- kirillklimuk 4mo agohonestly, worth a try! might be easier for the LLMs than authoring CLI commands.
- rnxrx 4mo agoThis is great - and another example of how much more efficient CLI tool use ends up being in actual day-to-day use. Claude Code and Hermes took it in and it runs great in my initial tries at it. Thanks for making and sharing it!
- dbcooper 4mo agoThere have been a few similar posts on HN recently for working with MS Office docs: https://github.com/iOfficeAI/OfficeCLI https://github.com/iOfficeAI/OfficeCLI https://github.com/rcarmo/python-office-mcp-server https://github.com/rcarmo/python-office-mcp-server https://github.com/espressoplease/smalldocs https://github.com/espressoplease/smalldocs It would be great to see some benchmarks for token use, correctness, features etc.
- kirillklimuk 4mo agofair point! i've got some stats in the body of the github, and a skill that has the eval that i've built for it.
- StackOptimist 4mo ago[flagged]
- DenisM 4mo agoFor A while I was expecting that MCP will dominate, but we seem to be going in the direction of CLI being more prevalent. Can’t wrap my mind around it.
- kirillklimuk 4mo agoSame - but when I did a lot of work with these tools, it became clear to me they're a lot more trained on working with CLIs. There's just much more data available for them to train on.
- madikz 4mo ago[flagged]
- egyptianblue 4mo agoIs there a generalizable approach that you have found for finding ways to be more efficient with the models, or is it case-by-case?
- kirillklimuk 4mo agoStill working it out as I build more of these CLIs. That being said: - every single command you write MUST have a help text. that help text should also tell agents what the easiest path forward it. for example, the locator system in this CLI relies on the positions on paragraphs. these can change after an edit. so I prompt in the help text to use batch edits. - errors must be clearly marked. for example, if an agent is doing a replace, but the replace comes back with "0 edits made", that's an error. otherwise the agents carry on going on obliviously. - a lot of the CLI tools decide to use JSON as the default output. I started out that way as well. for agents, that immediately means having to invoke jq or a similar other tool to get it to be understood. the weaker the model, the worse they do on that. I found that providing markdown with annotations beats JSON on most tasks. - use image reading as a last resort. if it's possible to give the model the information it needs as text, it will do a better job working with it than it will thinking through an image. thus, for this CLI, i do have a render command, but explicitly prompt in the help texts to use it for things that are not obvious from the markdown like layout.
- kirillklimuk 4mo agoalso, batched commands do wonders. if the agent wants to make multiple changes at once, give it the facility to do so. this is done via --batch in the CLI and is especially important since the underlying positional markers shift.