Coding Agents for Historical Research

Python tools, project workflows, and delegated research

Bas Machielsen

What is a coding agent?

Accessing a model from Python

Models can be accessed through a browser or an application programming interface (API). An API lets a Python program send prompts and receive responses. chatlas handles this communication and maintains the conversation.

from chatlas import ChatAnthropic

chat = ChatAnthropic()
chat.chat("Explain what a company director does.")
chat.chat("How does that differ from a shareholder?")

Python program

Provider’s API

Model

Response

Requires an API credential. Setup instructions are in the reference slides.

chatlas: getting started

The browser is one interface to a model; Python provides another. API means a specified interface through which programs exchange requests and responses. The second call continues the conversation: chatlas resends the necessary history. The provider executes the model remotely. This slide displays code, not a live API call. Explain the constructor and chat method without explaining HTTP or JSON. API credentials and CLI subscription sign-in are separate setup routes. All Python examples in this chapter continue with the same chat object.

Giving the model a function

A tool is a function made available to the model. The model requests a call and supplies its arguments. The surrounding software executes the function and returns its result.

def multiply(x: int, y: int) -> int:
    """Multiply two integers exactly."""
    return x * y

chat.register_tool(multiply)
chat.chat("Use multiply to calculate 20598162 × 83106206.")

Illustrative tool display; product checked with Python

Tool request: multiply(20598162, 83106206)
Tool result: 1711835094393372

Python adaptation of Wickham, Your LLM can’t math. chatlas tool calling.

A tool is ordinary code. The type annotations and docstring tell chatlas how to describe the function and its arguments to the model. register_tool makes the function available; Python performs the arithmetic. The model chooses the arguments rather than calculating the product itself. The displayed request is illustrative, not a claim that an API session was recorded. The exact product is verified in the offline example. Hadley’s original uses R; all displayed code here is a separately labelled Python adaptation.

Giving the model access to files

The same mechanism gives a model access to project files. Reading supplies information; writing creates a saved research output.

from pathlib import Path

def read_file(path: str) -> str:
    """Read a UTF-8 text file."""
    return Path(path).read_text(encoding="utf-8")

def write_file(path: str, content: str) -> str:
    """Save text to a UTF-8 file."""
    Path(path).write_text(content, encoding="utf-8")
    return f"Saved {path}"

chat.register_tool(read_file)
chat.register_tool(write_file)

Adapted from Wickham, coding-agent tools.

These are ordinary Python functions, with the same registration mechanism as multiply. The model chooses paths and content. The prepared workspace contains directors.csv. This minimal example explains file operations; established coding agents also constrain paths and permissions. It is not necessary to build these functions to use Claude Code or Codex. We use them here to explain what the software does on the model’s behalf.

From tool calls to an agent

chat.chat(
    "Read directors.csv. Summarize the directors, firms, "
    "and periods. Save the summary to director_summary.md."
)

Illustrative execution sequence

1. Model requests read_file("directors.csv").
2. Python returns the file contents.
3. Model requests write_file(...) with the summary.
4. Python saves it; the model reports completion.

Prepared output preview

# Director roster

## Directors and firms
F.H. Fentener van Vlissingen: SHV.

## Period covered
Service dates are not supplied.

An agent uses tools repeatedly, choosing its next action from the results. chatlas handles the tool-calling loop.

Wickham, What is an agent?; chatlas tool loop.

The model decides what to write after receiving the data. A single function request illustrates tool calling; this sequence illustrates several calls towards one objective. Define harness as the surrounding software that handles calls and results, with chatlas as the example. The output preview is a prepared illustration also saved by demo.py, not a recorded model-generated answer. Missing service periods remain missing; birth/death dates cannot be substituted. Show the input and resulting file together. Actual agents may use more calls or another order.

Tools for coding and research

Coding agents supply tools for inspecting files, editing code, and running commands. Web tools let them find sources and inspect their contents.

Tool	Example action
Read / list / search files	Locate and inspect directors.csv
Write / edit files	Create a Python retrieval script
Run a command	Execute the script and inspect its output
Web search	Find biographies or genealogy records
Web fetch / browser	Open a source and examine its contents

Write Python

Run it

Inspect the result

Choose the next action

Wickham, A coding agent is six functions in a trenchcoat

This tool inventory extends the minimal example. File search differs from web search. Search produces leads; reading the underlying source supports a claim. Available tools differ between products, and fetch is not necessarily a full browser. The agent can automate a repeated operation by writing code, then respond to unexpected results. Both capabilities are central to the research example.

The agent’s working environment

A terminal inside a project

A terminal accepts text commands. The shell interprets them and runs programs. Commands operate from a working directory, which determines where relative paths begin.

director_research/
├── directors.csv
├── director_summary.md
├── sources/
├── code/
└── outputs/

pwd                    # working directory
cd director_research   # enter the project
ls                     # list its contents
ls sources             # list source documents

sources/biography.md starts inside the working directory. .. refers to its parent directory. Launching an agent here gives it this workspace.

McDermott, command-line introduction; Utrecht, Introduction to Bash.

Commands use Bash-compatible syntax on macOS, Linux, or Windows WSL. Start in the folder containing director_research before the cd command. Absolute paths start from the filesystem root; relative paths start from the working directory. Describe a directory as a folder. The directory shown is the demonstration workspace, not a requirement to reorganize another research repository.

Running commands and saving output

An agent’s command tool can run the same programs as a person at the terminal. It can inspect output, identify a failure, and decide what to do next.

cat directors.csv
python code/summarize_directors.py
python code/summarize_directors.py > outputs/run.log

python is the program; the script path is an argument. > saves printed output to a file, replacing its previous contents.

Give the agent the task

Read directors.csv. Write a Python script that counts directors by firm. Run it, inspect the result, and save the script and a summary under code/ and outputs/.

Janssens, Data Science at the Command Line

The researcher can issue the prompt without typing these commands. The agent can write the script and execute it. cat prints a text file. A run.log contains stdout; a CSV the program writes is a separate artifact. Errors normally appear on stderr, so this redirection alone is not a complete diagnostic log. The outputs directory must exist first. The accompanying workspace includes the example script.

Why plain text and Markdown?

Find the director’s birth date and spouse in the biography. Save the evidence and add a section on unresolved identities.

Working document	What the agent needs to do
Scanned PDF	Recognize text from page images; check names and dates
DOCX or PPTX	Extract text from the document structure; check its order
Markdown	Read and search the text directly; edit the relevant section

The editable note

# Director research
## Identity
## Evidence
## Unresolved identities

Plain text exposes the contents directly to file tools. Markdown expresses headings, links, and code within that text. Changes can be inspected line by line.

This is one concrete task with different preparation requirements. Agents can process other formats with suitable tools, but extraction adds a step. An image-only PDF has no searchable text until recognition takes place. PDFs with a text layer still need extraction and checks for reading order. DOCX and PPTX are packaged documents, not files that ordinary text tools can read as research prose. Markdown can be read without the originating application and works well with version control. Use it for instructions and evidence notes; tables remain CSV or Parquet. The next slide supplies the conversion step.

Converting documents into Markdown

Convert PDF, DOCX, and PPTX material into Markdown for the project’s working documentation. Check names, dates, tables, and reading order against the original.

anydoc sources/biography.pdf -o sources/biography.md
anydoc sources/notes.docx -o sources/notes.md
anydoc sources/slides.pptx -o sources/slides.md

Convert the source documents to Markdown with anydoc. Check the passages containing names and dates against the originals. Identify documents requiring OCR and record extraction problems.

Keep originals for verification. Scanned PDFs require OCR; anydoc reports this by default.

Commands checked against local anydoc --help, 30 September 2026.

Use Markdown as the working copy, retaining originals as evidence. anydoc handles one document per invocation and -o names the output file. Default handling rejects PDF pages needing OCR with exit code 3. Hosted OCR can be configured separately; see references. Conversion does not make extraction correct automatically.

Working with an agent

Launching an agent

Start the agent from the project directory. Claude Code and Codex provide interactive sessions in which an agent can inspect files, run commands, and save work.

Claude Code

cd director_research
claude

Codex

cd director_research
codex

Enter a task in the session. Read the response, inspect the files it creates, and continue with follow-up instructions.

Claude CLI; Codex CLI.

Choose either command for the demonstration. These are alternatives starting from the parent folder, not consecutive commands to paste. Installation and sign-in are in the reference slides. The interactive interface provides a composer for prompts and shows actions. Tool access and permissions determine what actions are available. Launching a coding agent does not require the chatlas program from Chapter 1: the product already supplies its model connection and tools.

Specifying the task and output

Read directors.csv. Summarize the directors, firms, and periods represented in the file. Save the summary to outputs/director_summary.md. Report missing information explicitly and list the files created.

A task specifies the input, objective, and required output. Naming a file makes the work available outside the conversation.

Structure of the saved file

# Director roster
## Directors and firms
## Period covered
## Missing information

The prompt deliberately uses the same roster as the opening. The agent can create outputs if needed. The terminal response should identify what it saved; inspect the actual file. Missing information is preferable to invented dates. At this stage the task concerns the roster contents, not additional web research.

Working interactively

Initial instruction

Summarize the director roster and save it to outputs/director_summary.md.

Follow-up

The period column describes service at the firm, not the person’s lifespan. Revise the summary to make that distinction explicit.

Further instruction

Add a section listing the information needed to distinguish directors with similar names. Base it on the columns actually present in the roster.

Follow-up instructions can correct an interpretation, change the task, or request further work. The agent can revise the saved file in the same session.

This is an illustrative exchange, not a recorded agent error. The follow-up explains how to correct a period interpretation if that problem occurs in a roster containing a period column. Our small saved roster has empty service dates, so the prepared summary reports them missing. Do not pretend that the agent made the illustrated error. The researcher can ask to see changes or the agent’s rationale before revising the file.

Persistent project instructions

CLAUDE.md and AGENTS.md provide project instructions across sessions: commands, research conventions, and output locations.

# Director research
## Commands
Run scripts with Python.
## Evidence
Compare names, dates, places, and family.
Save source URLs and identity decisions.
Record unresolved cases.
## Outputs
Save notes and tables under outputs/.

When AGENTS.md does not exist

ln -s CLAUDE.md AGENTS.md

The symbolic link gives both filenames the same contents.

Other coding agents, including Cursor, also exist. Their instruction conventions differ.

Claude project memory; Codex AGENTS.md; Wickham, coding agents.

Claude Code reads CLAUDE.md and Codex reads AGENTS.md. ln -s target link makes a symbolic link, so editing the target updates the text available through either filename. The accompanying workspace supplies the shared file and link. Commands are for Unix-compatible shells; Windows users can use WSL. Instructions provide context and are not infallible enforcement. Avoid promising identical discovery rules across products. This compact instruction file is a teaching example.

Running a saved prompt

Save this task as prompts/summarize.md

Read directors.csv.
Summarize the directors, firms, and service periods.
Write outputs/director_summary.md.
Report missing information and list the files created.

Claude Code

mkdir -p outputs
claude -p < prompts/summarize.md \
  > outputs/claude-summary.md

Codex

codex exec --sandbox workspace-write \
  -o outputs/codex-summary.md - \
  < prompts/summarize.md

The requested research file and the agent’s final message are separate outputs.

Claude CLI reference; Codex non-interactive mode.

-p and exec select non-interactive execution. Input redirection < supplies the prompt. Codex’s final dash reads stdin; -o saves the last message. Claude’s stdout redirection saves its response. Both tasks separately request director_summary.md. Create outputs for either command, and run alternatives separately. Configure needed tool permissions before an unattended run; an operation that requires a fresh approval can fail. We do not run agent commands when rendering or replaying this presentation.

A research workflow

The research task

Starting from a director roster, identify each director’s parents, children, and spouse. Research those relatives’ firm affiliations and record the sources.

Worked row from a demonstration roster

Director	Birth year	Firm
Frederik Hendrik Fentener van Vlissingen	1849	SHV

Family relationships

Firm affiliations

Supporting sources

Save separate tables with identities, roles, dates, and source links.

Director and family details. Workflow adapted from the genealogical research in my paper.

The roster is a small teaching input assembled from documented information, not an extract from the paper’s empirical sample. Follow one worked director through this chapter. The focus is a nineteenth-century Dutch business family with cross-firm affiliations in the next generation. No service dates for the root are assumed. The source lists his SHV occupation; the archive records below anchor his identity and family. His son has the same full name, born in 1882.

How the agent approaches the task

Director roster

Source records

Relatives

Affiliations

The agent can write Python for repeated retrieval and table construction. It can also inspect the evidence, change a query, choose another source, and assess identities.

Repeated operation	Decision after inspecting results
Query an API for each director	Which name variant should be tried next?
Retrieve linked family records	Does this concern the director or his son?
Combine affiliation rows	Does the source establish a directorship or ownership?

Both columns can be work performed by the coding agent. Once written, Python runs its specified operations; the model chooses subsequent actions from what it observes. An agent can also change the code if retrieval fails. This is a division by operation, not a division where people must do one column. The researcher determines the task and evidence standard.

Writing and running a source query

Write Python to search OpenArchieven for the director’s full name. Run it and inspect the candidate records.

import requests

def search_records(name: str) -> dict:
    response = requests.get(
        "https://api.openarchieven.nl/1.1/"
        "records/search.json",
        params={"name": name, "number_show": 5},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["response"]

result = search_records(
    "Frederik Hendrik Fentener van Vlissingen"
)

Saved API response: 71 person mentions

Event year	Role
1962	Deceased
1962	Father
1918	Deceased

A person mention is not a distinct individual.

OpenArchieven API query, retrieved 30 September 2026.

The function sends a request and returns the response object containing number_found and docs. number_show limits the returned page, not the total match count. This count is from a saved response and may change on the live site. The first two mentions occur in the same death record, with different roles. The code retrieves candidates; the next step is to interpret them. The script is displayed and not executed during rendering. The offline replay reads the saved JSON. Request errors must be inspected, not treated as evidence of absence.

Responding to the results

1. The full-name query returns different people and record roles.
2. The attempted Geni page is inaccessible; research continues in GenealogieOnline.
3. The family tree supplies a spouse and marriage date as leads.
4. An OpenArchieven marriage record identifies the groom born in 1849, his spouse, and parents.

Distinguish the director born in 1849 from his son. Compare roles, dates, spouse, and parents. Open the records and save the identity decision with its reasons.

Accepted anchor: marriage in 1879; groom born on 21 September 1849.

Family-tree lead; 1879 marriage record.

This is a condensed prepared walkthrough of sources inspected on 30 September, not a verbatim transcript of a separately launched Claude session. The Geni profile linked via Wikidata returned an access-block response; GenealogieOnline loaded and provided leads. The marriage JSON and its archive source corroborate names, birth date, spouse, and parents. Geni profile attempted: https://www.geni.com/profile/index/6000000014962271156 (the son). Access failure caused a source change, not a no-match decision. Research also used web search and biography inspection; the saved evidence notes document the steps.

Retrieving the family

Join people to their marriage-record roles

people = {
    person["@pid"]: person
    for person in record["Person"]
}
roles = {
    relation["RelationType"]:
        people[relation["PersonKeyRef"]]
    for relation in record["RelationEP"]
}
father = roles["Vader van de bruidegom"]
mother = roles["Moeder van de bruidegom"]
spouse = roles["Bruid"]

Simon Paulus + Anna Maria Veldhuijs

↓ parents

F.H., born 1849 + Lijntje Roosenburg

↓ son

F.H. (Frits), born 1882

Python extracts recorded relationships. The agent checks identities and investigates conflicting or incomplete links before expanding the family.

1879 marriage; son’s 1962 death record.

record is the retrieved marriage JSON; the full retrieval code is in the accompanying Python example. @pid identifies a person mention within a record. It is not a global identity key shared by all sources. The mapping joins RelationEP references to Person entries. This works for the demonstrated single-marriage event and roles; a general adapter must handle repeated roles. The marriage supplies the director’s parents and spouse. The son’s death record names the same father and mother, corroborating the son link. Sources retain their own identifiers until identity linkage is checked. An archive index is used here; no claim is made that handwriting on the original scans was checked.

Researching affiliations

Research F.H. Fentener van Vlissingen, born in 1882. Try his full name, Frits, and F.H. with company and role terms. Open the sources. Record supported firms, roles, and dates. Use newly found firms for follow-up searches and keep unresolved questions explicit.

"Frits Fentener van Vlissingen" commissaris
"F.H. Fentener van Vlissingen" Hoogovens
"Frederik Hendrik Fentener van Vlissingen" KLM

Biography: paraphrased evidence

Hoogovens: delegated supervisory director, 1918–1945; chairman of the supervisory board, 1945–1953.

A biography supplies firms and roles that guide subsequent searches. The same task repeats for the other identified relatives.

De Vries, Biografisch Woordenboek van Nederland.

The person packet contains the birth year and family evidence to distinguish namesakes. The biography identifies SHV, Hoogovens, KLM, and other firms, and provides dated Hoogovens roles. The displayed extract is an attributed paraphrase, not a screenshot or verbatim quotation. Query examples illustrate the worker’s possible follow-ups; do not present them as an executed search log. Preserve role types rather than merging employment, ownership, and supervisory offices. The offline replay exports only the two curated Hoogovens rows; it is not an exhaustive affiliation survey of this person or his relatives.

The resulting research files

Supported affiliations of the director’s son, born in 1882

Firm	Role	Period
Hoogovens	Delegated supervisory director	1918–1945
Hoogovens	Chairman of the supervisory board	1945–1953

outputs/
├── identities.md
├── family.csv
├── affiliations.csv
└── unresolved.md

Python combines the saved rows. Notes retain identity decisions and sources.

Relatives whose affiliations have not been established remain unresolved.

Both roles: Biografisch Woordenboek van Nederland. Links are retained with the exported rows.

Show the saved output using python presentations/coding_agents/demo.py, then open demo-output/affiliations.csv and identities.md. The script replays inspected archive evidence and curated affiliation decisions without web or model calls. It does not claim autonomous discovery. The family.csv has separate IDs for father and son. Other affiliations and the rest of the family remain questions; missing research is not a zero or a negative outcome. Hoogovens supplies a cross-firm affiliation relative to the original director’s SHV role.

Delegating research tasks

Assigning a task, leaving the steps open

A research worker receives an objective, input information, and an output location. It chooses searches and follow-up actions from the evidence it finds.

Research the firm affiliations of F.H. Fentener van Vlissingen, born in 1882. Use the identified family record to distinguish namesakes. Choose suitable queries and follow source leads. Save firms, roles, periods, and URLs to outputs/people/fhfv-1882/affiliations.csv. Save evidence and unresolved questions alongside it.

Inspect evidence

Choose a search

Read a source

Assess and save

This prompt defines the research objective and artifacts, leaving intermediate steps to the worker. It can also write Python when repeated retrieval would help. The researcher still defines scope and evidence standards. This is a proposed worker prompt; the offline replay does not launch a model or any workers.

Spawning research agents

The main agent can delegate separate people to subagents. Each worker conducts its investigation and returns findings to the coordinator.

Spawn two research subagents. Assign one the director’s son, born in 1882, and the other his spouse, Lijntje Roosenburg. Give each the identified person record and affiliation-research task. Each saves files in a separate person folder. Wait for both, then summarize findings and unresolved questions.

Coordinator

Son’s research worker

Spouse’s research worker

Coordinator collects results

Claude subagents; Codex subagents.

Enter this instruction in an interactive Claude Code or Codex session with the required research tools available. Built-in delegation creates the workers; no Python orchestration framework is needed. Each worker has its own context and makes its own model and tool calls. Explicitly give workers instructions and input paths rather than assuming every product shares all parent context. The two workers research the son and spouse of the root born 1849, not the son’s spouse. The diagram is illustrative, not a screenshot of an executed run.

Reviewing and combining their work

Read both workers’ notes and rows. Check the assigned identities and whether sources support the roles and periods. Request further evidence where necessary. Use Python to combine reviewed rows into outputs/affiliations.csv and collect unresolved questions in outputs/unresolved.md.

outputs/
├── people/
│   ├── fhfv-1882/
│   └── roosenburg-1860/
├── affiliations.csv
└── unresolved.md

The coordinator reviews and combines the investigations. The researcher decides whether the evidence is sufficient for the analysis.

Coding agents can produce repeatable code and conduct searches that adapt to results. Saved code, evidence, and decisions make that work inspectable.

End the main talk here. Review is a separate action, not something guaranteed by adding workers. Independent tasks can run in parallel; shared final files should have a single owner. More workers consume additional model calls. The replay supplies separate packets and prompts but does not pretend every relative was researched. Reference material follows. Content takes precedence over a fixed speaking time; the README records the chapter structure instead of a twenty-minute speaking schedule.

Reference material

Installation and sign-in

Claude Code: macOS, Linux, or WSL

curl -fsSL https://claude.ai/install.sh | bash
claude auth login
claude

Codex: npm installation

npm install -g @openai/codex
codex login
codex

Run the installed agent inside the project. For web research in Codex, use codex --search. Check the installed version’s tool and permission settings before running saved prompts unattended.

Claude setup; Codex CLI. Commands checked 30 September 2026.

These are reference commands, not commands run by the presentation. Codex’s npm route requires Node.js and npm; native alternatives and Windows instructions are in its official docs. CLI account sign-in differs from the API key used by chatlas. Tool permissions need to allow the task’s file writes and commands. Do not bypass all permissions to make the demonstration work; do a small interactive run first.

Python API setup and accompanying examples

Install chatlas and its Anthropic provider dependency:

python -m pip install chatlas anthropic
export ANTHROPIC_API_KEY="your-api-key"

Offline research replay: from the website repository

python presentations/coding_agents/demo.py

Optional API example: from the prepared workspace

cd presentations/coding_agents/demo-workspace
python code/chatlas_example.py

The replay needs only Python’s standard library. The optional API example makes model calls; rendering the presentation does not.

chatlas Anthropic setup

The project-managed Python command may be uv run python rather than python, as appropriate to the user’s environment. The API key is a placeholder; provide it through an environment variable and do not save credentials in project files. The demonstration workspace is rebuilt by demo.py. The API example is optional and was not run as part of preparing the deck. It uses only read/write/multiply inside the prepared workspace and leaves the saved fixtures separate.

Conversion and OCR

anydoc --help
anydoc sources/biography.pdf -o sources/biography.md

# For a scanned PDF: hosted OCR
anydoc sources/scan.pdf --ocr hosted -o sources/scan.md

Hosted OCR sends the document to the configured service. Set up its API access as described by the installed tool. Check the result against the source images.

Exit code	Meaning
0	Conversion completed
1	Reading or conversion failed
2	Invalid invocation
3	PDF pages need OCR under default handling

Verified with local anydoc --help, 30 September 2026.

This is the tool already used for the repository’s style-reference documents. Local installation does not establish a public package installation command, so we do not invent one. FIRECRAWL_API_KEY or the tool’s –api-key option can supply hosted credentials. Check current help for provider configuration. The files in these conversion commands are illustrative user-provided documents.

Sources: agents and command-line work

Hadley Wickham: What is an agent?

Hadley Wickham: Your LLM can’t math

Hadley Wickham: A coding agent is six functions in a trenchcoat

chatlas: Python model access and tools

Paul Goldsmith-Pinkham: agentic coding introduction

Grant McDermott: command-line introduction

Utrecht: Introduction to Bash

Jeroen Janssens: Data Science at the Command Line

Sources: the worked family

GenealogieOnline: director born in 1849

OpenArchieven: 1879 marriage, BHIC record 148

OpenArchieven: son’s 1962 death, BHIC record 86

Joh. de Vries: Fentener van Vlissingen, Frederik Hendrik (1882–1962), Biografisch Woordenboek van Nederland

Geni profile attempted: son born in 1882

Evidence inspected on 30 September 2026. Geni access failed. The replay uses saved archive responses and curated decisions; it is not an exhaustive affiliation survey.