Skip to content
BSWEN
Blog

Why Does Asking Claude for Word Documents Slow Down Your Session?

Cowrie
Cowrie
Dev @ Bswen

Problem

I asked Claude to write me a Word document. The response took forever, my token usage spiked, and I watched the little “thinking” animation spin for what felt like an eternity.

Me: Can you create a Word document with a project proposal?


Claude: [spins for 30+ seconds]
[container initializing...]
[importing python-docx...]
[building document structure...]
[applying styles...]


[Finally produces a .docx file]


Token usage: +2,500 tokens
Time: 45 seconds

I just wanted a simple document. Why did it take so long and cost so many tokens?

Environment

  • Claude AI (web interface)
  • Request: Create a Word document (.docx)
  • Expected: Fast response, minimal overhead
  • Actual: 30-45 seconds delay, 500-2000+ extra tokens

What Happened?

Claude writes in markdown natively. That’s its native output format. But when I asked for a Word document, I forced Claude to take a detour through code execution.

Here’s what Claude actually does when you request a .docx:

1. Spin up a code execution container (Sandboxed Python environment)
2. Install/import python-docx library
3. Write Python code to build the document programmatically
4. Apply styles, formatting, and structure
5. Run the script
6. Generate the .docx file
7. Return the file to you

Every single one of these steps takes time and tokens. And most of them are unnecessary.

The Docx Conversion Pipeline

Here’s an ASCII diagram of what happens when you ask for a Word document:

┌─────────────────────────────────────────────────────────────────────┐
│                    YOUR REQUEST FOR DOCX                            │
│                 "Create a Word document..."                         │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  STEP 1: CODE GENERATION                            │
│  Claude writes Python code to create the document                   │
│                                                                     │
│  from docx import Document                                          │
│  doc = Document()                                                   │
│  doc.add_heading('Project Proposal', 0)                            │
│  doc.add_paragraph('This is the content...')                       │
│  ... (hundreds of lines of code)                                   │
│                                                                     │
│  Token cost: 500-1500 tokens for the code itself                   │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  STEP 2: CONTAINER STARTUP                          │
│  Spin up a sandboxed Python environment                             │
│                                                                     │
│  - Allocate container resources                                     │
│  - Install python-docx if not cached                                │
│  - Set up file system                                               │
│                                                                     │
│  Time cost: 5-15 seconds                                            │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  STEP 3: SCRIPT EXECUTION                           │
│  Run the generated Python script                                    │
│                                                                     │
│  - Parse and execute the code                                       │
│  - Build document structure                                         │
│  - Apply styles and formatting                                      │
│  - Generate the .docx file                                          │
│                                                                     │
│  Time cost: 5-20 seconds                                            │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  STEP 4: FILE RETURN                                │
│  Send the generated .docx back to you                               │
│                                                                     │
│  Token cost: Minimal (just the file reference)                      │
└─────────────────────────────────────────────────────────────────────┘


TOTAL OVERHEAD:
- Time: 30-45 seconds
- Tokens: 500-2000+ extra tokens

Compare this to what happens when you ask for markdown:

┌─────────────────────────────────────────────────────────────────────┐
│                 YOUR REQUEST FOR MARKDOWN                           │
│               "Write a markdown document..."                        │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  DIRECT OUTPUT                                      │
│  Claude generates markdown directly                                 │
│                                                                     │
│  # Project Proposal                                                 │
│                                                                     │
│  This is the content...                                             │
│                                                                     │
│  Token cost: Just the content tokens                                │
│  Time cost: Normal response time (2-5 seconds)                      │
└─────────────────────────────────────────────────────────────────────┘


TOTAL OVERHEAD:
- Time: 2-5 seconds
- Tokens: Content only

The difference is dramatic. Markdown is native. Docx requires an entire pipeline.

Token Waste Analysis

I measured the token difference between asking for markdown vs. docx:

Request TypeInput TokensOutput TokensTotalTime
Markdown505005503s
Docx502000+2050+35s

The docx request consumed nearly 4x more tokens and took 10x longer. Why?

Because Claude had to generate this code first:

docx_generated_code.py
from docx import Document
from docx.shared import Pt, Inches
from docx.enum.text import WD_ALIGN_PARAGRAPH


# Create document
doc = Document()


# Add title
title = doc.add_heading('Project Proposal', 0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER


# Add sections
doc.add_heading('Overview', level=1)
doc.add_paragraph('This project aims to...')


doc.add_heading('Timeline', level=1)
doc.add_paragraph('Phase 1: Research (2 weeks)')
doc.add_paragraph('Phase 2: Development (4 weeks)')


doc.add_heading('Budget', level=1)
table = doc.add_table(rows=4, cols=2)
table.style = 'Table Grid'
# ... more code for tables, formatting, etc.


# Save document
doc.save('project_proposal.docx')

Every line of this code costs tokens. And you pay for it even though you’ll never see or use this code.

The Double-Penalty Problem

Here’s the worst part: if you want to edit that Word document later, you pay the penalty twice.

First request: "Create a Word document..."
- Claude generates code + runs it + returns .docx
- Cost: 2000 tokens, 35 seconds


Second request: "Add a section about risks to that document..."
- Claude cannot directly edit .docx files
- Claude must RE-GENERATE the entire document
- Regenerate code + re-run + return new .docx
- Cost: Another 2000 tokens, another 35 seconds

Each edit is a full regeneration. There’s no incremental editing of .docx files. The container spins up again, the code runs again, everything happens from scratch.

Common Mistakes I Made

Mistake 1: Asking for .docx when I only needed to read the content

I requested Word format because “that’s what my client uses.” But I just needed to review the content first. I should have started with markdown, reviewed it, then converted to .docx at the end.

Mistake 2: Iterating on a Word document

I asked Claude to “revise the .docx” multiple times. Each revision cost me 2000+ tokens and 30+ seconds. I should have worked in markdown until the content was final, then converted once.

Mistake 3: Not knowing about local conversion

I didn’t realize I could convert markdown to .docx locally with pandoc. One command does the job instantly.

The Solution: Work in Markdown, Convert Locally

Here’s my new workflow:

Step 1: Create content in markdown

Me: Write a project proposal in markdown format.


Claude: # Project Proposal


## Overview
This project aims to...


## Timeline
- Phase 1: Research (2 weeks)
- Phase 2: Development (4 weeks)
...


Token cost: 550
Time: 3 seconds

Step 2: Review and iterate in markdown

Me: Add a section about potential risks.


Claude: ## Potential Risks
- Resource constraints...
- Technical challenges...


Token cost: 200
Time: 2 seconds

Iterating in markdown is fast and cheap. Each revision costs normal token rates, not the inflated docx rates.

Step 3: Convert to Word locally

Once the content is final, I convert it locally using pandoc:

terminal
# Install pandoc (one-time)
brew install pandoc  # macOS
# or: apt install pandoc  # Linux
# or: choco install pandoc  # Windows


# Convert markdown to docx
pandoc proposal.md -o proposal.docx


# With custom styling
pandoc proposal.md -o proposal.docx --reference-doc=template.docx

The conversion happens instantly on my machine. No tokens. No waiting. No container overhead.

Pandoc Conversion Examples

Here are some useful pandoc commands I use:

terminal
# Basic conversion
pandoc input.md -o output.docx


# Use a Word template for styling
pandoc input.md -o output.docx --reference-doc=my-template.docx


# Add a table of contents
pandoc input.md -o output.docx --toc --toc-depth=3


# Convert with metadata
pandoc input.md -o output.docx --metadata title="My Document"


# Batch convert all markdown files in a directory
for f in *.md; do pandoc "$f" -o "${f%.md}.docx"; done

For more complex documents, I create a reference template:

terminal
# 1. Create a reference document (opens in Word)
pandoc -o reference.docx --print-default-data-file reference.docx


# 2. Edit reference.docx in Word to set your styles


# 3. Use the template for conversions
pandoc my-document.md -o output.docx --reference-doc=reference.docx

When You Actually Need Claude-Generated Docx

There are edge cases where asking Claude for .docx makes sense:

  1. You have no local environment - Using Claude on a phone, tablet, or restricted machine where you can’t install pandoc
  2. Complex programmatic formatting - You need dynamic tables, calculated fields, or conditional formatting that’s easier to express in code
  3. One-and-done documents - You’ll never edit it again, so the conversion cost is acceptable

But for 95% of use cases, the markdown-first workflow is superior.

Comparison Summary

AspectMarkdown WorkflowDocx Workflow
Initial generation3 seconds35 seconds
Token cost (initial)Content only500-2000+ extra
Revision costNormalFull regeneration
Iteration speedFastSlow (30s+ per revision)
Final formatConvert locallyAlready .docx
Total time (3 revisions)~10 seconds~2 minutes
Total tokens (3 revisions)~1000~6000+

Summary

In this post, I explained why requesting Word documents from Claude causes session slowdown. The key point is that Claude’s native output format is markdown, and asking for .docx forces code execution with significant overhead.

This workflow reduces your token costs by 4x, speeds up iteration by 10x, and gives you more control over the final formatting.

Stop paying the docx tax. Use markdown, convert locally.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: