nbdev 3.3.0 makes notebooks less hostile to Git and agents

What changed

nbdev 3.3.0 adds three related capabilities:

• directive parsing has moved into cell methods, with support for notebook-level metadata directives;
• a Git diff driver can present notebook changes more usefully than a raw JSON diff;
• structural repair can recover malformed or inconsistent notebook structure.

The companion fastcore 2.1.3 release adds cell-editing tools plus line- and expression-hash utilities. Taken together, the releases provide a more deliberate editing surface for notebooks rather than expecting every tool to rewrite the entire document.

There is also a small post-release nbdev changelog formatting fix. That is maintenance noise, not the reason to pay attention.

Why it matters

Jupyter notebooks are useful working documents and awkward software artefacts. Their JSON representation mixes executable code, prose, metadata, outputs and generated identifiers. A minor cell edit can therefore create a noisy diff, while a generic text-editing agent can damage structure that a human would never intentionally touch.

That matters once agents are allowed to maintain research, documentation or notebook-driven libraries. The important shift in nbdev 3.3.0 is not “AI for notebooks”. It is the lower-level plumbing that makes automated work reviewable and recoverable:

1. Structural diffs improve approval. A reviewer can inspect meaningful cell changes instead of wading through serialised notebook churn.
2. Cell-aware edits reduce blast radius. An agent can target a unit of work rather than regenerate a whole .ipynb file.
3. Structural repair gives automation a recovery path. Notebook corruption becomes something tooling can detect and fix, not merely a failed parse at the end of a run.
4. Notebook-level directives make intent explicit. Repository behaviour can be carried as metadata instead of inferred from brittle conventions.

For Foundry, Hermes and OpenClaw, this is relevant where notebooks sit inside an agent workflow. It does not change the agent runtime itself, but it improves the artefact boundary the runtime operates against.

My read

Worth a spike, not an estate-wide update.

Take one disposable nbdev project and test a short agent workflow: modify a code cell, modify a markdown cell, inspect the Git diff, deliberately introduce a mild structural fault, then run repair and export. Compare the resulting patch with the same changes made through generic JSON or text editing.

The acceptance test is boring on purpose: the diff should be understandable, unrelated cells should remain untouched, export should succeed, and a second run should be idempotent. If those conditions hold, cell-aware notebook operations are worth packaging as a guarded Hermes or OpenClaw skill.

Do not upgrade a production nbdev project solely because 3.3.0 exists. Pin the current environment, run the project’s existing tests and inspect directive behaviour first; parser and metadata changes can affect repositories that depend on older conventions.

Bottom line

nbdev 3.3.0 is a useful agent-tooling update because it treats notebooks as structured, reviewable artefacts. The public signal is modest but real: Git-aware diffs, repair and cell-level editing are the sort of unglamorous controls that make automated notebook maintenance safer. Spike it on one notebook workflow; update production only after the generated code and metadata remain stable.