Bench Folder

A benchmark is a folder — a standard Bun TypeScript project with a shape Axon knows how to read, the same as agents and modules.

my-bench/
├── bench.config.ts     # the contract — factors, measurements, dimensions
├── tests/              # execution — standard Bun test files
├── template/           # copied into a fresh workspace per run
├── README.md           # methodology and limitations
├── package.json        # dependencies
└── .bench/             # generated — do not edit

What each part does

bench.config.ts — the published contract. Declares what the experiment varies (factors), what it measures (measurements), how results slice (dimensions), and what evidence is kept (artifacts). See The Config.

tests/ — .bench.ts files, run with Bun's test runner against each cell of the factor matrix. See Writing Tests.

template/ — the material the subject operates on. Copied fresh into a workspace for every run, so subjects never share state.

README.md — the methodology. Shown on the registry; say what the benchmark measures, how, and where its limits are.

.bench/ — generated output: type declarations for your declared measurements, run workspaces, results. Recreated by the runner; never edit it.

Creating a benchmark

axon bench new my-bench

Scaffolds the folder with a minimal config — one boolean success measurement, an empty template, and an example test.