Your AI agent edited the Word file. Can you get the original back, byte for byte?
You ask an agent to change one payment term in a contract. It does. The file opens, and the sentence is right.
Now answer two questions about that file. What else changed? And can you get back the exact file you had before?
If an agent edits a .docx file in place, can you get the original back? Unless you made a copy first, the answer is often no.
When history starts, ASTra stores the exact bytes of your document before it parses them (automatically through the MCP server, with astra history --init on the command line), and it can hand them back or put them back in place. You can check the result with sha256sum, without trusting us. This post describes version 0.5.3.
In short. ASTra is a source-available engine that lets AI agents create and edit Word (.docx) files, through an MCP server, a command line and a TypeScript library. It runs on your machine.
- The original file is kept byte for byte, with its SHA-256, when a document’s history is first created. You can export it to a new file, or restore it in place as one recorded step that you can undo.
- Around it: typed edits in all-or-nothing batches, a check of every save with Microsoft’s Open XML SDK validator, and a git-backed history with preview and revert.
- Cost: storing the original adds a little to the first open of a document. On a CI machine a 200-page file opens in about 2.5 seconds the first time and about 1.3 seconds when it is opened again.
- See the page: the agent can look at it.
visual_inspectrenders a page to an image with Word on Windows (when Word is installed) or LibreOffice, and--show-markupdraws tracked changes and comments. - Not solved: one writer per document. Two processes saving the same file can still lose an edit.
Why “it looks fine” is not enough
A .docx is a ZIP package of XML parts, images and the relationships between them. A program that opens it and saves it again will usually write the XML a little differently, even if nobody asked for a change. ASTra does this too: on the first save it normalizes word/document.xml and adds paragraph IDs. The text is the same. The bytes are not.
For a blog draft, nobody cares. For a signed agreement, a filing, or a template that forty people depend on, “the same text” is a weaker promise than the one your colleagues assume. They assume that if the agent gets it wrong, the file they gave you still exists.
An agent adds a second problem. It works fast, in several steps, and you were not watching. If step three was a mistake, you want to see the steps, undo them, and in the worst case throw everything away and return to the start.
What ASTra does
There are now two separate guarantees. They are easy to confuse, so here they are side by side.
| Revert and redo | Original export and restore | |
|---|---|---|
| Goes back to | Any saved state in the history | The file as it was before ASTra first touched it |
| What matches | Every package part, as saved | Every byte of the file, checked by SHA-256 |
| Whole-file bytes identical | Not promised (the ZIP is written again) | Yes |
| Recorded in history | Yes, as a new commit | Restore: yes, one commit. Export: no, it only writes a copy |
When a document first gets a history, ASTra reads its bytes from disk before parsing them, stores them next to the history, and records the hash. Export and restore return those bytes only after reading them back and checking the hash again. If the check fails, ASTra tells you why and does not hand you a substitute.
Try it in two minutes
You need Node.js 22.19 or newer. Use any .docx you have, or make one:
npm install -g @attentionform/astra
printf '# Services agreement\n\n## Fees\n\nThe Customer will pay each invoice within thirty (30) days of the invoice date.\n' > msa.md
astra create contract.docx --from-md msa.md
On the command line, history is opt-in. Turn it on before the first edit. That is the moment the original is captured.
$ sha256sum contract.docx
c07ffc7c...bbf038d contract.docx
$ astra history contract.docx --init
astra: original captured, sha256 c07ffc7c...bbf038d
HISTORY INIT contract.docx: recorded baseline d205b42 (9 tracked package files); 1 commit.
Make an edit and check the result against the Office schema:
$ astra batch contract.docx --target-text "thirty (30) days" \
--append "The Customer will pay each invoice within forty-five (45) days of the invoice date."
BATCH OK contract.docx -> contract.docx (applied=1 normalized=0)
$ astra validate contract.docx
VALID contract.docx
$ sha256sum contract.docx
57898962...8cda83d contract.docx
The file is different now, as it should be. Get the untouched original out as a separate copy, and compare:
$ astra history contract.docx --export-original untouched.docx
EXPORT ORIGINAL OK untouched.docx
$ sha256sum untouched.docx
c07ffc7c...bbf038d untouched.docx
The same hash as before the edit. Export does not change the working file and will not overwrite an existing file unless you pass --force.
Or put the original back in place:
$ astra history contract.docx --restore-original
RESTORE ORIGINAL OK contract.docx: exact original bytes restored; commit ff9c369
$ sha256sum contract.docx
c07ffc7c...bbf038d contract.docx
$ astra history contract.docx
ORIGINAL available, sha256 c07ffc7c...bbf038d
HISTORY contract.docx: 3 commits, head ff9c369
ff9c369 ... Restore original file (sha256 c07ffc7c...bbf038d)
6403c72 ... batch: 1 operation(s) (replace)
d205b42 ... Initial state
The restore is recorded as a commit like any other. If you restored by mistake, one astra revert contract.docx brings the edited version back:
$ astra revert contract.docx
REVERT OK contract.docx: restored 6403c72 "batch: 1 operation(s) (replace)" (steps=1); new commit 35749bd
Hashes are shortened here and yours will differ, because your file is not ours. This output is a real run of the published @attentionform/astra@0.5.3 package on Linux, on 16 November 2026. In that run the reverted file had the 45-day text again and passed astra validate, but its hash was 89b8212d...bb45272, not 57898962...8cda83d. That is the first column of the table above: revert restores the document, not the ZIP bytes.
With an agent
Through the MCP server you do not need the --init step. The original is captured when an existing document first gets a history, and every successful save is recorded. The server has 21 tools. Two of them are export_original_document and restore_original_document. open_document and get_document_history report original.available, or the reason it is not available.
claude mcp add astra -- npx -y @attentionform/astra-mcp-server --allowed-dir "$PWD"
--allowed-dir is the only folder the server may read and write. The Connect page has the setup for Claude Desktop, Cursor, Windsurf and others. Then ask for what you want:
Open contract.docx. Change the payment term from 30 to 45 days as a tracked change. Save it, show me the history, and export the original to untouched.docx.
What we measured
Recovery. The run above is one file. We also ran export and in-place restore through the MCP server on our 40-document test corpus. For all 40 files, the exported original had the SHA-256 of the file as it was before the first open. That held when we exported before any edit and after an edit and a save, and restoring in place gave the same hash. Two conditions: the corpus is generated by scripts, not written in Word, and we ran the 0.5.3 release commit built on the CI machine, not the package downloaded from npm. The recovery tests also run in CI on Linux, Windows and macOS.
Speed. Storing the original costs time on the first open of a document. We measured it through the MCP server on a GitHub-hosted Linux machine with 4 threads, in two rounds. Each number is a median of 30 opens, over both rounds. The runner code, the raw results and a summary computed from them are in the benchmark branch.
| File | First open | Open again |
|---|---|---|
| 200 pages | 2.53 s | 1.33 s |
| 200 pages, validation off | 2.26 s | 1.04 s |
| 200 pages, 20 MB of media, validation off | 3.38 s | 1.19 s |
Opening the same file again takes about half as long as the first time. Small files open fast: a 1-page file in about 0.23 seconds and a 10-page file in about 0.26 seconds. One edit, a save and a validation of those small files took 0.24 s, 0.67 s and 0.67 s. These are tool times on a shared cloud machine. They depend on the machine and the file, and they leave out the model’s thinking time.
What else we checked. On the same run, our other tests gave these results: 1,047 of 1,047 edits changed the content of no other paragraph, and 108 of 108 rejected batches left the document unchanged. Every document in these tests was generated by a script, and the damaged files we use to test the schema check were damaged by a script we wrote, so these numbers say little about the mess in real files. The full report also has the other results: the outline is a median 2.89 times smaller than the XML in tokens, the save check caught 81.6 percent of our injected faults, and a revert restores every package part (300 of 300); only the ZIP wrapper (timestamps, entry order) is written again, so no content is lost and exact-file recovery is what the stored original is for. ASTra is early and changes every day, so these numbers and the limits below will move. The protocol was committed before the first measurement. The page renderer is not part of this benchmark, nor are the charts, tables and page-layout controls.
Where it stops
These limits describe version 0.5.3. We are working on several of them and expect them to change.
- One writer per document. Two ASTra processes saving the same file at the same time are not coordinated. In our test, two MCP servers each changed a different paragraph of one file and saved together. This was a deliberate stress test on one setup. Both edits survived in 0 of 30 trials: in 4 one edit was lost, and in 26 neither edit was in the file. Give each document to one agent at a time, or give each agent its own copy. Making this safe, so that edits to different paragraphs merge and edits to the same paragraph are reported as a conflict, is the next piece of work.
- The original lives next to the document, in the hidden
.astrafolder. Delete or lose that folder and the original is gone. It is not a backup. The location also needs a filesystem with hard links. NTFS, ext4, APFS, XFS and btrfs have them. FAT, exFAT and some network shares do not, and ASTra then says so and stores nothing. - Sanitizing does not clean the original.
astra sanitizecan remove author names, comments and tracked changes from the working file. The stored original and the earlier history still hold them. Send the sanitized file, not the folder. - A valid file is not a correct document. The schema check tests structure. It does not know whether your figures are right or the page looks right. Looking at pages as images needs a renderer: LibreOffice, or Word on Windows; Poppler is also needed on Linux and macOS. Word and LibreOffice paginate differently, and the Word checks used one Word build on one machine.
- Word only. ASTra edits
.docx. It does not edit Excel or PowerPoint files.
Licence
ASTra is source-available under the Business Source License 1.1. It is not open source. Production use is free for people who work alone, schools and academic research, non-profits, public bodies, organizations with up to 10 people and under USD 250,000 revenue, and products with under USD 250,000 revenue. Other production use needs a commercial licence. Trying it out is free for everyone. Each version becomes Apache-2.0 four years after it is published. The licensing page and pricing explain who needs what.
Next step
Take a document that matters to you and run the six commands above on it. Compare the two hashes yourself.
npx -y @attentionform/astra history your-file.docx --init
If it fails on your file, that is the report we want most: open an issue with the error and, if you can share it, the file. If you plan to use it at work and are above the free limits, write to us and tell us about your documents.
Try ASTra. Connect it to your AI assistant in about a minute, or read how it works.
Found a mistake, or a document where ASTra fails? Open an issue.