🪱 deword

Create, read, edit, fill, patch, and add real equations to Word documents — without breaking formatting.

Word docs are awful for agents: ZIP archives, fragmented runs, hidden media, and XML everywhere. deword turns them into something agents can actually work with, and now also lets them create new .docx files and insert real Microsoft Word equations.

Install

# Homebrew (macOS/Linux)
brew install alexandersvozil/tap/deword

# npm (any platform with Node.js 18+)
npm install -g deword

# Zero-install
npx deword --help

First-time agent quick start

If you are seeing deword for the first time, start here:

deword help
deword new draft.docx
deword read draft.docx -f summary
deword formula draft.docx --replace "<empty>" --latex "E = mc^2"
deword read draft.docx

For an existing document:

deword read report.docx -f summary
deword read report.docx -f model

Pick the right command

| Need | Command | |---|---| | Create a new .docx | deword new <file> | | Inspect a document | deword read <file> | | Get structure for agent work | deword read <file> -f model | | Insert a real Word equation | deword formula <file> ... | | Replace one exact unique string | deword edit <file> --old ... --new ... | | Replace all occurrences / placeholders | deword replace <file> --old ... --new ... or --map | | List form fields | deword fields <file> | | Fill fields / checkboxes | deword fill <file> ... | | Do multi-step structural edits | deword patch <file> -p patch.json | | Inspect unpacked XML/media | deword unpack <file> | | Use raw XML as an escape hatch | deword xml <file> ... |

Quick start

# Create a new document from the bundled template
deword new report.docx

# Read
deword read report.docx

# Insert a real Word equation (OMML / Math Mode)
deword formula report.docx --replace "<empty>" --latex "E = mc^2"

# Edit one exact unique text occurrence
deword edit report.docx --old "Draft Report" --new "Final Report"

# Replace all occurrences / template placeholders
deword replace report.docx --map replacements.json

# Fill form fields
deword fill form.docx --field "Employee Name" --value "John Smith"
deword fill form.docx --field "I agree" --check

# Read an agent-friendly document model
deword read report.docx -f model

# Apply a high-level JSON patch plan
deword patch report.docx -p patch.json -o final.docx

Creating new documents

deword new report.docx
deword new report.docx --text "Quarterly Board Memo"
deword create drafts/note.docx

Creates a new .docx from the bundled template.

By default the document contains a single <empty> placeholder so agents can immediately target it with:

• deword edit
• deword replace
• deword formula
• deword patch

Use --text to replace the placeholder during creation.

Formulas / equations

deword formula report.docx --replace "<empty>" --latex "E = mc^2"
deword formula report.docx --after "Financial Model" --latex "\\frac{Revenue - Cost}{Revenue}"
deword math report.docx --append --latex "x_1 + x_2 = y"

This inserts a real Microsoft Word equation in OMML / Math Mode. The result opens in Word as an actual editable equation, not plain text and not hand-written XML.

Supported syntax today

Practical LaTeX-style subset:

• superscripts/subscripts: x^2, x_1, x_1^2
• fractions: \\frac{a+b}{c}
• radicals: \\sqrt{x}, \\sqrt[n]{x}
• functions: \\sin(x), \\log(x)
• common Greek letters / symbols: \\alpha, \\beta, \\pi, \\leq, \\geq, \\neq, \\infty

Location modes

• --replace "..." replace a uniquely matched body paragraph
• --after "..." insert after a uniquely matched body paragraph
• --before "..." insert before a uniquely matched body paragraph
• --append append to the end of the document body

Current scope

formula currently inserts displayed equation paragraphs. It is ideal when you want a standalone formula block in Word. For more advanced layout or unsupported math syntax, use multiple formula insertions, patch, or xml as a last resort.

Reading

deword read report.docx              # markdown (default)
deword read report.docx -f json      # structured JSON
deword read report.docx -f model     # agent-friendly structure with IDs
deword read report.docx -f summary   # metadata + preview
deword read report.docx -i ./imgs    # custom image extraction dir

What you get:

• markdown with headings, bold, italic, tables, and links preserved
• images auto-extracted to a temp directory by default
• metadata in YAML frontmatter
• merged fragmented Word runs for cleaner reading
• formula previews rendered as readable plain text in read

Editing

edit — surgical single replacement

deword edit report.docx --old "Q4 2025" --new "Q4 FY2025"
deword edit report.docx --old "Draft" --new "Final" -o final.docx

Use edit when the old text should match exactly once across the document. If it matches 0 or more than 1 times, deword fails and tells you to add more context.

Search scope includes:

• body
• headers
• footers
• footnotes
• endnotes

replace — batch/template replacement

deword replace report.docx --old "{{NAME}}" --new "John Smith"
deword replace report.docx --map replacements.json

Replaces all occurrences.

JSON map format:

{
  "{{NAME}}": "John Smith",
  "{{DATE}}": "2025-01-15",
  "{{COMPANY}}": "Acme"
}

fields / fill — form fields and checkboxes

deword fields form.docx
deword fields form.docx -f json
deword fill form.docx --field "Name" --value "John"
deword fill form.docx --field "I agree" --check
deword fill form.docx --json data.json

Batch JSON format:

{
  "Employee Name": "John Smith",
  "Start Date": "2025-01-15",
  "I agree": true
}

patch — high-level agent editing plan

deword patch report.docx -p patch.json
deword patch report.docx -p patch.json -o final.docx

Use patch for multi-step or structural edits when edit or replace is too narrow.

Example:

{
  "version": "1.0",
  "operations": [
    {
      "op": "replace_text",
      "target": { "by_text": { "text": "Draft Report", "match": "exact" } },
      "new_text": "Final Report"
    },
    {
      "op": "insert_footnote",
      "anchor": { "by_text": { "text": "assumption", "match": "exact" } },
      "footnote_text": "Confirmed with finance on 2026-03-28."
    },
    {
      "op": "insert_table",
      "location": { "after": { "by_heading": { "text": "Financial Summary", "level": 2 } } },
      "data": [["Metric", "Value"], ["Revenue", "$14.1M"]],
      "table_style": "professional"
    },
    {
      "op": "insert_image",
      "location": { "after": { "by_heading": { "text": "Market Overview", "level": 1 } } },
      "file_path": "chart.png",
      "width_px": 480,
      "alignment": "center",
      "caption": "Figure 1. Regional sales chart"
    }
  ]
}

Current patch ops:

• replace_text
• replace_all
• edit_paragraph
• insert_paragraph
• insert_footnote
• edit_footnote
• insert_table
• edit_table_cell
• append_table_row
• insert_image
• set_region_text
• fill_field
• set_checkbox

unpack — deep inspection

deword unpack report.docx -o ./docx-work

Creates agent-friendly files such as:

• CONTENT.md
• content.json
• xml/
• media/
• manifest.json

xml — safe escape hatch

deword xml report.docx
deword xml report.docx -p word/styles.xml
deword xml report.docx --list
deword xml report.docx --set word/document.xml -i new.xml

Use XML mode only when higher-level commands cannot express the change.

Recommended agent workflow

Existing document

deword read <file> -f summary
deword read <file> -f model
# choose edit / replace / fill / formula / patch
deword read <file>

New document

deword new <file>
deword formula <file> --replace "<empty>" --latex "E = mc^2"
# or deword edit / replace / patch
deword read <file>

Formats

| Input | Read | Edit | |---|---|---| | .docx (Word 2007+) | ✅ Full | ✅ Full | | .doc (MHTML/Web Page) | ✅ Full | ❌ | | .doc (Legacy binary) | ❌ Clear error | ❌ |

Detection is by magic bytes, not extension.

Agent integration

deword help

The CLI help is designed to be enough for a first-time agent:

deword help
deword help formula
deword help patch

AGENTS.md

This repo includes an AGENTS.md file at the root. Agents that support that convention can pick it up automatically.

Pi skill

Copy the skill/ directory into your Pi skills folder:

cp -r skill/ ~/.pi/agent/skills/deword

Or add it to your project’s .pi/skills/ directory.

Zero-install via npx

npx deword read document.docx
npx deword edit document.docx --old "foo" --new "bar"

Why not just python-docx?

| | Raw XML | python-docx script | deword | |---|---|---|---| | Tokens (1.1MB docx) | 198,613 | 5,600 | 6,255 | | Formatting preserved | ❌ | ❌ | ✅ | | Tables | ❌ | Bare text | ✅ Markdown | | Images | ❌ | ❌ | ✅ Auto-extracted | | Real Word equations | ❌ | Fragile/manual | ✅ | | Editing | Manual XML surgery | Fragile | ✅ One command | | Round-trips | 0 | 2-3 | 1 |

License

MIT