$31,500. That is what the reading behind this article would have cost at API list prices: at least 25 billion tokens. I paid a monthly subscription.
In August I went on holiday with one document: my grandfather's birth entry, number 418 of 1926, in the civil registry of Estremoz. Eleven weeks later I can open a baptism written on 10 August 1666 and read the names of people I descend from.
I did not go to an archive. I did not learn palaeography. Most of it was done from a phone.
Open archives, closed handwriting
Portugal's archives are extraordinary, and few people know it. Priests recorded baptisms, marriages and burials from the sixteenth century on. Notaries kept their deeds. Orphans' courts inventoried the estates of the dead who left heirs. The army kept a page on its soldiers, down to the colour of their eyes. The district archives and the national archive have photographed a huge part of it and put it online, free to view.
The images are there. What was missing was a way to read them at scale. A 1690 baptism is a photograph of a hand, with abbreviations, water stains, and a script that changes with every new priest.
What the pages said
This is the part that feels like time travel. Not names and dates, but rooms, faces and silences.
- A lieutenant of artillery died at Estremoz in 1796 without a will. The orphans' court walked through his house and wrote it down over a hundred and fifty pages: four rooms upstairs and four down, on the Rua do Mau Foro, vineyards paying a ground-rent in grape must to the House of Braganza, a gold chain, six silver spoons, a two-year-old heifer. He could write. His widow could not, and asked a neighbour to sign for her.
- A carpenter's son enlisted at seventeen, on 27 January 1764. The army roll gives his hair, his eyes and his height, four feet ten inches by the old measure. It also lists his wars: the Roussillon and Catalonia campaigns of 1793 to 1795, against revolutionary France. He retired a major in 1810, forty-six years after his oath.
- At five in the morning on 13 September 1875, a baby came through the foundling wheel of Alter do Chao, wrapped in an old cloth, with no note and no token. No parent was ever written down. That line stops at a church door, and the record says so.
- On 1 November 1755 the great earthquake destroyed Lisbon. The registers of four of the family's Alentejo parishes were read for that autumn. Not one priest wrote a word about it. An absence, read at scale, is a finding too.
- My great-grandfather was an office clerk who composed. The Portuguese authors' society lists 110 works in his name, and the national library's catalogue lists no published score under his name. Seven manuscripts the family kept were transcribed to notation and rendered to audio, and you can hear them on the site. Nobody in the family had heard a note.
The numbers
- 360 years: the oldest dated record in the tree is a baptism of 10 August 1666.
- 12 generations on the direct line, 479 people in the tree.
- 77,987 page images, 64 GB, from 727 archive units: parish books, church-court files, orphans' inventories, notarial deeds, army rolls, civil registers.
- 2,369 transcription files of the pages that mattered, some covering several images.
- At least 25 billion tokens of reading, over 132,000 requests.
- About $31,500 at API list price, roughly 40 cents a page. On a monthly subscription, it cost the subscription.
The stack, for the nerds
Claude Code ran in a Docker container on a small VPS, inside one tmux session I reached over SSH from my phone. No IDE and no notebook: a terminal, a git repository, and a lot of Markdown.
- Why a phone is enough. Nothing runs on the phone. It opens an SSH connection, with a key, into a tmux session on the server, sends a prompt and reads the answer. Claude downloads, crops, reads and writes on the server. The 64 GB of images never touch the phone.
- Dropped connections do not matter. When the signal goes, in a tunnel or on a beach, tmux keeps the session and its agents running. The next connection lands exactly where the last one left off.
- Long jobs, short check-ins. A margin sweep of a whole register or a batch of four agents runs for an hour or more on its own. From the phone the loop is: read the report, answer a question, start the next batch.
- Fetch. Python scripts call the digitarq API of the Portuguese national archives and pull whole books, image by image, into one folder per archive unit. FamilySearch images come through the logged-in session's own token. The army's historical archive refuses curl and headless browsers, so a headed Brave runs with remote debugging, and a Node script downloads each leaf from inside the page over the DevTools websocket.
- Read. No OCR: it was no use on these hands. ImageMagick crops and enlarges, the model reads the picture with vision, and it writes a Markdown transcription with the abbreviations expanded and the doubtful words marked [?].
- Let code do the cutting. Vision tokens are the bill, so the model writes code to avoid spending them. Priests wrote the name of the child or the couple in the margin beside each act. A shell script crops that margin column from both pages of every opening, normalises the contrast, and splices the strips side by side into one image. One image read then indexes a whole run of pages instead of one. The full act is opened where a margin names someone we want, and every act without a margin note is read in full, because the index cannot clear it. It became a standing rule after a reading agent spent three hours on 147 full images of a single book.
- Calibrate first. Two or three known entries are checked by eye before any sweep. A margin that abbreviates can leave out the very name you are looking for, and a sweep that was never calibrated manufactures a false negative: a whole book wrongly declared empty.
- Fan out. Long mechanical reads go to sub-agents, four at a time. Thirteen at once killed eleven of them on the shared session limit.
- Models. Opus 5 did most of the reading, Fable 5 and 5.1 the hardest leaves, Sonnet 5 the bulk sweeps. Nine tenths of the tokens are cache reads: one long context, re-read at every step, with a new page dropped in each time.
- Second opinion. A GPT model re-reads the contested words. Its answer is advice, never a verdict: every claim goes back to the image.
- One source of truth. A single GEDCOM file holds the tree, and every fact in it cites its source. FINDINGS.md is the lab notebook, 18,574 lines. NEGATIVES.md, 7,564 lines, records every search that found nothing, so nothing gets searched twice.
- Publish. One Python script turns the GEDCOM into a static site in four languages, deployed to Cloudflare Pages. The music goes from ABC notation to MIDI, through timidity and ffmpeg, to MP3, with a cue file so the score follows the sound.
One rule held the whole thing together. Every fact in the tree cites its source, and most point at a page image you can open. The rest say what they rest on: a catalogue description, an estimate, or family testimony.
Why the second model matters, and where it stops
On one pair of baptisms, from 1875 and 1878, the two models agreed on two names and disagreed on two others. Agreement is cheap confidence. The disagreements were the useful part: they marked the exact words to go back to. On both, the second model was wrong. And Claude's own conclusion on one of them, built on a deed of 1916, turned out backwards: a third baptism, from 1883, showed the surname belonged to the husband, not the wife.
A second reader is worth having. It is not an oracle. The referee is always another document.
The archives have their own traps, and a model alone falls into them. At Barbacena in 1747 there are two men called Manoel Gomes, both married to an Isabel Lopes, three openings apart in the same book. A match on names picks the wrong man. A younger sister's baptism, with its grandparents named, settled which one was ours.
What this makes possible
My family is one test case, and the method has limits: some books have no margin index, or one that misleads, and must be read page by page. But the archives are already online, and the same tools can be pointed at other parishes and towns.
- Read a whole village, not one family. The baptisms, marriages and burials of a parish over three centuries, as a dataset: population, epidemics, migration, the age at marriage, the foundlings.
- Measure literacy from signatures. Deeds and inventories record who signed and who asked someone to sign for them. Three centuries of who could write, street by street.
- Join archives that never talked to each other. Army rolls, parish books, notarial deeds and court files describe the same people from four angles. On my mother's side they trace a line of ten women, and a single birth record overturned a candidate the tree had carried for months.
- Give the diaspora a way home. Millions of people descend from Portuguese villages, in France, Brazil, everywhere. Many of their ancestors' pages are already online. What they lacked was a reader.
- Rebuild scenes from records, not imagination. Every scene of the film I am planning for the children of the family starts from a page that exists. The narration is the priests' own sentences. The soundtrack is my great-grandfather's music. Nothing in the story that is not in a record.
What changed
The archives were opened years ago. The reading was the bottleneck, and its cost has collapsed: the images are free to view, and the reading cost me one subscription and my evenings. What is left for the human is the part that was always the most valuable: checking identities, resolving contradictions, and saying plainly what is not known.
If you work on heritage, archives or open data in Portugal, I would like to compare notes. The tree, the documents and the music are at family.aiteklabs.com.
Archive images: Arquivo Distrital de Évora and Arquivo Distrital de Portalegre (DGLAB).