Plugin for agentic research in experimental physics

Agentic research is increasingly common in experimental physics, and verifying it is the hard part. PhysKit is a free, open-source plugin for Claude Code and Codex for collaborative agentic research: skills, prompts, templates, and code that give an AI agent the habits of a careful experimentalist and build those habits into the tools it works with, not just its instructions.

Install Case studies Preprint (arXiv) GitHub

Pre-release: the skills and doctrine still change between versions. Use the latest release.

Why it exists

AI agents can now do substantial research work, and their output can look right even when it is wrong. In experimental physics, where models are approximations and data carry noise and systematic effects and depend on apparatus details the agent cannot see, a result is only as good as the checks behind it. From our preprint:

Increasingly common, few guidelines. “The use of artificial intelligence (AI) in physics research is increasingly common, yet few guidelines exist for its effective use.”
Verification is the limiting step. “In all our case studies, we found that detailed verification and assessment of agentic results by human researchers is an essential task, generally replacing technical implementation as the limiting step of a research project.”
It takes intensive interaction. In our six case studies, campaigns “often required human redirection or iteration.”

PhysKit builds rigor into the system the agent works in, so that the researcher directs the work, can check what was actually found, and can build on it.

What PhysKit is

A tool for collaborative agentic research in experimental physics, designed to reduce the probability of errors and the burden of verification.

Standardized documentation

Each run is archived with its exact code, configuration and data, and every number is labeled by where it came from.

Easier human verification

Every result is labeled with how it was checked, up to an independent verifier at the level you set; reports map each claim to its evidence.

Closed-loop iteration

The agent proposes, runs, evaluates, verifies and records, toward a goal and a frozen metric you set. You can add ideas at any time.

What's inside

Skills: written procedures for recurring research tasks, such as framing a problem, verifying a result, designing a simulation, or writing a report.
A core prompt: the short set of rules for honest, verified, traceable work.
Templates: ready-made folder structures and documents for projects and research campaigns.
Code: the scripts that run campaigns, score results with a frozen metric, and label how each result was checked.

Two ways to use it

A general science toolkit

Skills for framing problems, verifying results, designing and validating simulations, dimensional analysis, deriving theory, debugging, and honest reporting. They work in any session; the agent picks the matching skill.

Closed-loop research campaigns

Scaffold and run a closed research loop — propose, implement, run, evaluate, verify, record, repeat — with a frozen honesty and verification core the loop cannot change, and health checks you can run while it works. How a campaign works ↓

Five skills to know by name

`frame-problem`	start any physics problem here — before modeling, simulating, or deriving
`verify`	check a result, number, or derivation before relying on it
`report`	write it up — every number labeled by provenance, every citation verified
`new-campaign`	stand up a closed-loop research campaign
`campaign-status`	health-check or checkpoint a running campaign

How a campaign works

1 · Setup

The agent interviews you first: the goal, the constraints, and the metric that will decide what counts as better. It runs a baseline experiment before anything changes, so every later result has something real to beat.

2 · Loop

Each cycle the agent proposes a change, implements it, runs it, and evaluates the result against the metric. Every result carries a label saying how it was checked, and every cycle is recorded, including the ones that failed. You can step in between cycles, or let it run.

3 · Report

When the goal is met, or you stop it, the claims are audited against the record before the report is written, and you decide what comes next.

Inside a campaign, as a grid of who does what (rows) in each stage (columns: setup, one loop unit, report). Researcher: describe the problem and approve the spec; optionally check in, steer, or resolve an escalation; decide next steps. Interactive agent: interview and frame, run a setup audit, act as concierge during the loop (launch, monitor, relay; it runs no experiments), and present the report. Driver, deterministic code: validate and preflight, spawn each worker with a brief, watch its heartbeat, score and run gates, assign the check each result is owed, and spawn the capstone. Workers, a fresh context each unit: propose, implement, run, evaluate, verify, record; the next unit reads the journal. Checks, by trigger and preset: unit tests and self-check every unit (minimal and up); self-verify for an implausible score (minimal, light); a surviving new best gets a peer check by the next worker (light) or a fresh verifier (heavy); every result gets a blinded verifier (intensive); the claim audit at the end of the campaign (minimal and up). Records on disk: frozen goal and metric, baseline experiment 000, journal, code snapshot with config and data, logbook and scoreboard, verdicts, the hook-guarded best result, and the verified report. — Inside a campaign: who does what at each stage, which checks each verification preset adds, and what is kept on disk. Colours match the stages in the figure above. Click to enlarge.

Case studies

Six case studies of collaborative agentic research from our quantum-sensing work, reported in the preprint (Sec. IV): very different projects, in simulation, on measured data, and on live hardware. They ran on earlier PhysKit versions, listed in the preprint; for new work, use the latest release.

A · Machine learning−33% error · synthetic

A typical synthetic test image: the published network's current map has broken segments; the campaign's network follows the wire pattern. Beside it, the mean test error over 34 experiments, ending 33% below the published network.

Current-density reconstruction

A network that outperforms our published one at recovering current maps from noisy magnetic images.

Synthetic test data · a typical test image

B · Model identificationbeats published

Simplified level diagram of the eleven-level model the campaign found (additions in teal), and the search score across the 101 model structures tested, dropping below the published model toward the counting-noise floor.

Quantum-defect photophysics

A photodynamic model of V_B⁻ defects in hBN that outperforms our published model.

Measured data

C · Device design2.7× vs first sweep · sim.

The junction of the final microwave design (copper traces around the hBN flake), and the simulated drive field across 313 designs, ending 2.7 times the best design of the agent's first size sweep.

Microwave device design

A fabrication-ready waveguide design with 2.7× the field of the best design in the agent's first size sweep.

Simulation

D · Quantum control>10× lower infidelity · sim.

The best robust pulse sequence (B1) over 49 experiments against the published yxx48 benchmark, and its performance as added site disorder grows, staying above yxx48.

Pulse-sequence design

A pulse-sequence candidate that beats the published benchmark by >10× and stays ahead under disorder.

Simulation

E · Hardware control~1 Hz · live hardware

Photo of the NV-NMR apparatus, and the figure of merit over 20.8 hours of experiments on live hardware, rising from an uncalibrated start.

NMR spectrometer commissioning

From an uncalibrated state to ~1 Hz frequency precision (best run; ten-run median 1.5 Hz).

Live hardware

F · Data analysis2,178 islands

Fit residual (measured minus fitted field) at 30.3 mT, at saturation, on the same pixels and colour scale: the baseline fit leaves 101 µT rms with strong edge artifacts; the joint fit leaves 20 µT rms.

Spin-ice microstate reconstruction

To our knowledge, the first such reconstruction from diffraction-limited magnetic imaging.

Measured data · fit residual at 30.3 mT (saturation) · baseline fit 101 → joint fit 20 µT rms

Try PhysKit

On GitHub now, as a pre-release. It works with Claude Code and Codex.

In a Claude Code session:

/plugin marketplace add Walsworth-Group/physkit
/plugin install physkit@physkit

In Codex, from your shell, then start a new session:

codex plugin marketplace add Walsworth-Group/physkit
codex plugin add physkit@physkit

Skills appear as /physkit:<name> in Claude Code and $physkit:<name> in Codex. Scopes, updating, pinning a version, other agents, and keeping the doctrine always loaded: the full install guide · getting started.

How it guards against errors

No single safeguard is trusted alone. Each layer covers gaps in the others.

Doctrine you read. An always-loaded constitution: truth over excitement, report every real evaluation (including failures), assume you're wrong until independently proven right, physical plausibility is a gate.
Procedures you follow. Skills written as step-by-step procedures — for example, verify checks a result by an independent route, not by re-reading the reasoning that produced it, and recomputes every reported number.
Structure you fill in. Templates with required slots and append-only records, so an omission shows up as a blank instead of disappearing.
Code that refuses. Executable gates — for example, a campaign can't promote a result under a stronger verification label than its checks earned, can't promote a refuted result, and can't promote anything while its correctness tests aren't passing.

The kit improves itself from reviews of real runs, but the honesty and verification core is frozen: a change that would weaken it is rejected outright.

FAQ

What is PhysKit?

A framework for AI coding agents doing experimental physics: skills, prompts, templates, and code, installed as one plugin. It has two layers: a general science toolkit you can use in any session, and a campaign layer that runs closed-loop research campaigns with a frozen honesty and verification core.

Which agents does it work with?

The full plugin installs in Claude Code and Codex. OpenCode and Gemini CLI can use the general skills (not campaigns) through a bundled installer — see the multi-agent notes.

What does it cost?

PhysKit is free and MIT-licensed. You need access to the agent you run it in (Claude Code or Codex), which is billed separately by its provider.

Do I need to run a campaign?

No. The general skills — frame-problem, verify, report, and the rest — work in ordinary sessions with no setup beyond installing the plugin. Campaigns are there when you want the agent to iterate on a problem in a closed loop, with you checking in and steering.

How does it keep an agent from fabricating results or citations?

Several ways, layered. Every result carries an honest label saying how it was checked — unverified, self-checked, or confirmed by an independent check — and the label travels with the number into every report. Every number in a report is labeled by provenance, cite-check verifies each reference against its source, and in a campaign executable gates refuse to promote a result under a stronger label than it earned. These reduce the risk; they don't remove the need for you to check work you build on.

Is it safe to let it run unattended?

Campaigns are designed for it: the setup interview front-loads your decisions, the evaluation is frozen so the loop can't quietly change how it is scored, a hook refuses to promote a result its checks don't support, and campaign-status lets you check its health at any point. Note that in Claude Code, the agents a campaign launches run without per-command permission prompts, because no one is there to answer them; their limits are the campaign's own checks and, for hardware, the instrument ranges you set at setup. Run campaigns in a project folder and on a machine where that is acceptable, and supervise them the way you would a new student: check in, and read the report critically.

Does PhysKit send my data anywhere?

PhysKit itself makes no network calls — it is skills, templates, and local scripts. Your agent sends your session to its model provider as it normally does.

Is it only for experimental physics?

That is the focus for now: its doctrine, templates, and checks are written for experimental physics — measurements, instruments, and the simulations around them. Some general skills (verification, honest reporting, debugging) may be useful elsewhere, but that is not what it was designed or evaluated for.

What does "pre-release" mean for me?

PhysKit is still pre-release: skills, templates, and doctrine still change between versions. Use the latest release; older versions stay tagged so that work which cites them can be traced.

How do I report a problem or suggest an improvement?

Open an issue on GitHub, or write to [email protected].

Cite

If you use PhysKit, please cite the preprint and the software version you used:

N. R. Reed, D. M. Daly, A. J. Beling, J. D. Giandrea, R. L. Walsworth, J. W. Blanchard, and D. Ang, Principles and Techniques for Agentic Research in Experimental Physics, arXiv:2610.17193 (2026).

@misc{reed_principles_2026,
  title         = {Principles and Techniques for Agentic Research in Experimental Physics},
  author        = {Reed, Niko R. and Daly, Declan M. and Beling, Andrew J. and Giandrea, Jordan D.
                   and Walsworth, Ronald L. and Blanchard, John W. and Ang, Daniel},
  year          = {2026},
  eprint        = {2610.17193},
  archivePrefix = {arXiv}
}

GitHub's “Cite this repository” button gives the current citation in BibTeX and APA.