Skip to main content
The Add PDF Reader skill enables NanoClaw agents to read and extract text from PDF files. It handles WhatsApp attachments, URLs, and local files using poppler-utils (pdftotext/pdfinfo).

​
What It Does

The Add PDF Reader skill:
  • Installs pdftotext CLI tool in container
  • Adds PDF reader script for agents
  • Auto-downloads PDF attachments from WhatsApp
  • Provides tools to extract text, fetch from URLs, and get metadata
  • Documents PDF capabilities for agents

​
Prerequisites

  • NanoClaw base installation complete
  • Container system configured (Docker or Apple Container)

​
How to Apply

1

Invoke the skill

Run /add-pdf-reader in your NanoClaw context.
2

Apply code changes

The skill runs npx tsx scripts/apply-skill.ts .claude/skills/add-pdf-reader which:
  • Adds container/skills/pdf-reader/ with CLI script and docs
  • Merges poppler-utils install into Dockerfile
  • Merges PDF attachment download into WhatsApp channel
  • Adds PDF tests to WhatsApp channel tests
3

Rebuild container

./container/build.sh
4

Restart service

npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

​
What Changes

​
Files Created

  • container/skills/pdf-reader/SKILL.md - Agent-facing documentation
  • container/skills/pdf-reader/pdf-reader - CLI script for text extraction

​
Files Modified

  • container/Dockerfile - Installs poppler-utils (provides pdftotext)
  • src/channels/whatsapp.ts - Adds PDF attachment download
  • src/channels/whatsapp.test.ts - Adds PDF download tests
  • .nanoclaw/state.yaml - Records skill application

​
Usage

​
WhatsApp PDF Attachments

Send a PDF file in any registered WhatsApp chat: 
You: [sends invoice.pdf]
Andy: I've received the PDF file "invoice.pdf". I can extract the text if you'd like.

You: What's the total amount?
Andy: [uses pdf-reader to extract text and finds total]

You: Extract all the line items
Andy: [extracts and formats line items from PDF]

​
PDF from URL

You: Read this PDF: https://example.com/report.pdf
Andy: [uses pdf-reader fetch to download and extract text]

​
Local PDF Files

In main channel with project mount: 
You: Read docs/specification.pdf
Andy: [uses pdf-reader to extract text from local file]

​
PDF Reader Commands

The agent has access to: 
# Extract text from PDF
pdf-reader extract <file.pdf>

# Fetch PDF from URL and extract
pdf-reader fetch <url>

# Get PDF metadata (pages, title, author)
pdf-reader info <file.pdf>
PDF attachments are automatically downloaded to attachments/ in the group workspace. The agent can reference them by filename.

​
Limitations

​
Text-Based PDFs Only

pdftotext only extracts text from text-based PDFs. For scanned PDFs (images):
  • Text extraction will be empty
  • Consider using agent-browser to open the PDF visually
  • Or use OCR tools (not included in this skill)

​
No Image Extraction

Images in PDFs are not extracted. Only text content is available.

​
Troubleshooting

​
Agent Says “pdf-reader command not found”

Container needs rebuilding: 
./container/build.sh
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

​
PDF Text Extraction Is Empty

The PDF may be:
  • Scanned (image-based) - pdftotext only handles text PDFs
  • Encrypted - some encryption blocks text extraction
  • Corrupted - check if PDF opens normally
Test manually: 
docker run --rm -v $(pwd)/groups/test:/workspace/group \
  nanoclaw-agent:latest /bin/bash -c \
  'pdf-reader extract /workspace/group/attachments/file.pdf'

​
WhatsApp PDF Not Detected

Verify:
  • Message has documentMessage field
  • MIME type is application/pdf
  • WhatsApp connection is active
Check logs: 
tail -f logs/nanoclaw.log | grep -i pdf
Look for “Downloaded PDF attachment” or “Failed to download PDF attachment”.

Build docs developers (and LLMs) love

Get started for freeTalk to us