kirillklimuk

also, 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.

Same - 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.

Still 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.

fair 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.

Realistically... 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.

honestly, worth a try! might be easier for the LLMs than authoring CLI commands.

That's pretty cool!

Yeah, I agree. Working on something like this for PDFs.

Not 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.

If 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.

I 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 =).

Heya folks! I built docx-cli this past weekend because my wife was getting tired of doing repetitive, rubric-based grading. At 20-30 mins a student with ~25 students, this was a lot of work.

So, I came in and told her I'd build a TA agent for her, only to run into Claude mangling a bunch of docs. I did what any engineer would do in this situation: got nerd-sniped into making a tool to edit Word files.

It clicked for me that if I:

1. Made the CLI tool edit in track-changes mode without committing

2. Wrote some fancy commenting across different spans

3. Prevented untouched / unrecognized parts of the doc from being borked

Then it would basically have the same protections we engineers expect from git but for Word files. Nothing mangled, and she was happy to decide which changes to keep.

So I did that and plugged it into my TA agent, and, lo and behold, some good rubric-based grading happened.

And then, as a former founder, I realized that this would actually be good for a bunch of things like contract redlining and so forth, so I decided to share with all y'all. Along the way, I made the tool read things out as markdown (since agents are good at it), and fixed a bunch of edge cases for things like moved tracking changes.