Let your AI assistant log your runs

If you write your simulation and plotting scripts with the help of an AI coding assistant, Claude Code, Cursor, Copilot, or any other agent, that assistant can also make every run it writes self-logging, with no hand-editing from you. This is not a new client or a new API: it is two small, free files that teach an assistant to follow the same manifest convention you would otherwise apply by hand, and it works the same on a laptop or a cluster, with or without ClusterPilot.

Two drop-in artefacts

Fieldnotes ships both in integrations/ai/:

• agent-rules.md is a short, tool-neutral rules fragment. Paste it into whichever rules file your assistant already reads: CLAUDE.md, AGENTS.md, .cursorrules, or a Copilot instructions file. From then on, that assistant follows the convention in that project.
• claude-code/fieldnotes-log/ is a Claude Code skill. Copy the fieldnotes-log folder into ~/.claude/skills/ (or a project's .claude/skills/), and Claude Code invokes it automatically when you write, edit, or run a data-producing or plotting script in a Fieldnotes project.

Both wrap the same convention and reuse the same emitter snippets, shown below.

What the assistant is told to do

1. Inject a manifest emitter. Right after a script's parameters are set, the assistant adds a couple of plain lines that dump those parameters to a params.json beside the outputs. This is your own data, not a Fieldnotes call:

import json
from pathlib import Path

params = {"size": 64, "seed": 7, "method": "baseline"}   # the script's own parameters

Path("results/manifest").mkdir(parents=True, exist_ok=True)
with open("results/manifest/params.json", "w") as f:
    json.dump(params, f)

or in Julia:

import JSON3

params = (size = 64, seed = 7, method = "baseline")   # the script's own parameters

mkpath("results/manifest")
open("results/manifest/params.json", "w") do io
    JSON3.write(io, params)
end

These are the same snippets as examples/emit_manifest.py and emit_manifest.jl, reused verbatim.

2. Log the finished run. Once the run has produced its outputs, the assistant runs fieldnotes log from the command line, pointing at the script, the manifest, and each real output and figure:

fieldnotes log --script run.py \
  --params results/manifest/params.json \
  --output results/data.out \
  --figure figures/plot.png \
  --tag baseline

For a whole array of runs, each with its own manifest directory, the same --manifest glob from logging array jobs applies unchanged.

The honest caveat

This is a convention, not a guarantee. An assistant following a rules file is helpful, not infallible: it can forget to add the emitter, or emit the wrong parameters if it is not told what the run actually varies. It complements the command line and the manifest path; it never replaces them. If a manifest is ever missing, the run can still be logged by hand with a plain fieldnotes log call. And the emitter itself only ever writes out your own parameters as plain JSON: it never imports Fieldnotes into your script, never adds a Fieldnotes call, and never invents a value the script does not already set.

See also

• The manifest convention: what a manifest is and why logging happens separately, as its own step.
• Logging array jobs safely: the same convention applied to a SLURM or PBS array, single-writer, after sync-back.