Plume

Fill any PDF form with a single command. Interactive fields, graphical forms, any language.

A Claude Code skill that reads your PDF, figures out the fields, fills them in, and verifies its own work.

Install • Usage • How it works • Tests • License

---

---

See it in action

Before	After /plume
AcroForm PDF — text fields, checkboxes, and dropdowns filled directly

Before	After /plume
IRS W-9 — mixed form: AcroForm fields + graphical signature overlay

Before	After /plume
Schengen visa application — graphical PDF with no interactive fields, filled via precise text overlay

---

Installation

1. Clone the repo:

git clone https://github.com/gi11es/plume.git
cd plume

2. Set up the virtualenv:

python3 -m venv .venv
.venv/bin/pip install -e .

3. Link the skill to Claude Code:

mkdir -p ~/.claude/skills
ln -s "$(pwd)/.claude/skills/plume" ~/.claude/skills/plume

That's it. /plume is now available from any directory.

Usage

/plume ~/Downloads/some-form.pdf

Plume will:

1. Analyze the PDF — detect whether it has interactive fields (AcroForm) or is a graphical form
2. Show you the fields it found and what it plans to fill
3. Remember your info from previous sessions — only ask for what's missing
4. Fill the form using the right strategy (direct field values or text overlay)
5. Verify the output visually and programmatically, self-correcting up to 3 times
6. Save your new info for next time

What it handles

PDF type	How Plume fills it
Interactive forms (AcroForm)	Sets field values directly — text, checkboxes, dropdowns
Graphical forms (no fields)	Reads the content stream, finds colored rectangles and labels, overlays text at exact coordinates
Mixed	Both strategies combined

Tested on 18 government forms from the US, UK, Germany, Spain, France, Italy, Portugal, Canada, Japan, Australia, and the EU — in 10 languages. See the full before/after gallery for all 18 forms.

How it works

PDF in --> Extract structure --> Map fields --> Fill --> Verify --> PDF out
               |                    |                     |
               v                    v                     v
          Content stream      Load memory           Visual check
          + AcroForm          Ask for missing       + coordinate check
          field detection     Save new data         (self-correction loop)

Three Python scripts do the heavy lifting:

Script	What it does
scripts/extract.py	Parses PDF content streams for text labels, colored rectangles, and checkboxes. Detects AcroForm fields with types, options, and positions.
scripts/fill.py	Fills forms via AcroForm field values or reportlab text overlay merged onto the original.
scripts/verify.py	Checks that filled text lands inside target field bounds. Returns a pass/fail JSON report.

Memory

Plume remembers your info between sessions in memory/user-info.json. On first run, copy the example:

cp memory/user-info.example.json memory/user-info.json

Then fill it with your details (or let Plume ask you interactively — it will save automatically).

Project structure

plume/
├── scripts/
│   ├── extract.py          # PDF structure parser
│   ├── fill.py             # Form filler (overlay + AcroForm)
│   └── verify.py           # Fill verification
├── memory/
│   ├── user-info.example.json  # Example data (committed)
│   └── user-info.json          # Your real data (gitignored)
├── tests/
│   ├── fixtures/           # 18 government PDF forms
│   ├── test_extract.py
│   ├── test_fill.py
│   └── test_verify.py
├── assets/                 # Logo + demo screenshots
├── .claude/
│   └── skills/plume/       # Claude Code skill definition
├── .venv/                 # Python virtualenv (created during install)
├── requirements.txt
└── pyproject.toml

Testing

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -v

312 tests run against 18 real-world PDF forms across 10 languages:

Form	Type	Language	Fields
US W-9 (IRS)	Mixed	English	23 + overlay
US W-4 (IRS)	AcroForm	English	48
US I-9 (USCIS)	AcroForm	English	128
US SF-86 (OPM)	AcroForm	English	6,197
UK N285 (HMCTS)	AcroForm	English	8
German Kindergeld	AcroForm	German/English	95
Spanish Modelo 030	AcroForm	Spanish	84
Foersom sample	AcroForm	English	17
Canadian TD1	Graphical	English	—
EU Schengen visa	Graphical	English	—
French Schengen visa	Graphical	French	—
German Schengen visa	Graphical	German/English	—
Italian Schengen visa	Graphical	English/Italian	—
Spanish Schengen visa	Graphical	Spanish/English	—
Portuguese national visa	Graphical	English	—
French long-stay visa	Graphical	English/French	—
Japan customs declaration	Graphical	English/Japanese	—
Australian passenger card	Graphical	English	—

Tests include AcroForm field readback verification (fill → read → assert value persists), graphical position validation (catches the all-zeros-bug), and regression tests for specific PDFs like the Schengen visa.

License

MIT