# ANT-1 opens the loop between a simulated ant and a synthetic neural controller

> ANT-1 is a browser based laboratory where a procedurally drawn ant explores an arena, senses odour, and returns to its nest under a 32 unit recurrent network with a learned action-value readout, and where you can silence sensors, freeze learning or erase memory mid-run. It suits people who want to watch an embodied control loop behave and intervene in it, and its own results are careful not to claim more than they show.

**ashleyotooligan/ant-1** — An embodied neural experiment connecting a simulated ant to a synthetic neural controller

- Repository: https://github.com/ashleyotooligan/ant-1
- Stars: 590 · Forks: 1
- Language: HTML
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ashleyotooligan-ant-1

## A laboratory you can open by double-clicking one file

ANT-1 describes itself as an open laboratory connecting an ant-inspired body to a synthetic neural controller, and the delivery mechanism is unusually direct. You download or clone the repository and double-click ANT-1.html. That self-contained edition embeds the application and its reference runs, and the README states that no Python, Node.js, API key, account or internet connection is required for the laboratory itself.

That constraint shapes the whole design. A simulation that needs a runtime, a package install and a network connection before it will show you a single frame is a different kind of artefact from one that opens in a browser tab. Here, the simulation, the drawing functions and the reference data are in one file that a lecturer can email to a student.

The release table records the current scope in one row: version 0.1.0, experimental, with a controller of 12 inputs, 32 recurrent units and 5 actions, a procedural ant in a 2D arena, and local, offline, no account execution.

For source development the README offers two local servers, and neither needs an install step:

```bash
npm start

# Or Python 3
python start_ant1.py
```

Both serve http://127.0.0.1:8000, and on Windows a Start-ANT1.bat launches the Python option. The package.json confirms the Node side needs no dependencies at all, with the engines field set to node >=22 and the start script pointing at scripts/serve.mjs.

The primary language of the repository is HTML, which is unusual and consistent with the delivery decision: the artefact a user runs is a document, and the source modules underneath it are shared with Node.

## The five parts of the loop, and where the engineering sits

The README organises the system as five inspectable things, and reading them in order explains the architecture better than any diagram would.

The first is a sensory boundary: two odour probes, obstacle channels, idealised navigation vectors, and internal-state inputs describe the current situation. The second is a neural state, a 32 unit leaky recurrent network that transforms the inputs into continuous internal activity. The third is a motor decision, where a learned action-value readout and an explicit, engineered steering prior choose one of five turns. The fourth is a consequence: the body moves, collides, reaches food, or returns to the nest. The fifth is an update, a temporal-difference learning rule that adjusts the readout, and the next observation closes the loop.

That ordering is the architecture. Everything happens inside one iteration of a single feedback cycle, and the intervention surfaces are ways to break individual links in it.

The design choice that deserves scrutiny is the engineered steering prior. The README says it makes the initial body useful to observe, and that the control protocols expose how much of its behaviour comes from that scaffold. The distinction matters because a hand-built navigation prior and a learned readout can look identical in a demo. The project is explicit that the network is a compact synthetic model and that its units and connections are not taken from an ant connectome, so nothing here is a claim about biology.

The figures are described with the same care. Figure 01 is seed 17 at step 900, rendered directly from the simulation and the application's drawing functions, and the caption notes that the documentation images are model figures, not browser screenshots or biological recordings.

## Five surfaces for observing and interfering

The observation surfaces are listed as a table, and each one is a different kind of access to the same simulation.

The Observatory is where you run, pause, step, change speed, inspect the ant, view sensory telemetry and export a session. The Neural interface is the intervention surface: you watch the recurrent core and motor values, silence sensors or units, freeze learning, erase memory, or move the food. Experiments run a fixed protocol and let you inspect its measured outcome. The Run archive lets you reproduce included runs and inspect the matched-seed benchmark. And External tasks cover an optional market-signal adapter that runs against a fresh instance of the controller.

The distinction between the Neural interface and the Experiments surface is the interesting one. The interface is free-form and manual: you choose what to break and when. The experiment surface is a fixed protocol with a measured outcome, so the intervention is repeatable and the numbers are comparable. The README makes the reproducibility promise concrete, since you can reproduce the resulting trajectory from a seed.

The ant's behaviour in one run is deterministic. The deterministic observation replay in the README is rendered from steps 680 to 1056 at seed 17, runs at 10 times simulated time, and loops back to its starting state.

There is also a node_modules-free architecture behind this. The src/core modules run in both the browser and Node, and the experiments directory defines the protocols, with the protocol definitions in experiments/protocols.js. That shared core is what lets the same code produce the interactive page and the command line runs, and it is why the figures in the documentation can be regenerated from the implementation rather than captured by hand.

## Seven protocols and the interventions they perform

The experiment programme is small and precise. Each protocol lasts 2,400 steps, equivalent to 240 simulated seconds, interventions occur at step 1,000, and the arena and seed can be held constant across conditions.

EXP-01 Navigation runs the full controller and asks whether it can find food and complete repeated returns. EXP-02 Relocation moves the food while retaining its old memory, to see how the loop responds to environmental change. EXP-03 Antenna silences the left odour and proximity inputs, to ask how dependent behaviour is on bilateral sensing. EXP-04 Frozen readout disables learning from the start, to ask what the plastic readout contributes. EXP-05 Memory erases state, readout and the food vector together, to ask what happens after a composite memory interruption. EXP-06 Recurrent intervention clamps units 00 to 07 to zero, to ask whether that changes the outcome. EXP-07 No steering prior removes the engineered navigation scaffold, to ask what the small learner can do without it.

Two details in that list are methodological rather than incidental. The interventions all happen at the same step, 1,000, so the conditions differ in what was changed rather than in when. And the arena and seed can be held constant, which is what makes the comparison a controlled one.

The composite nature of EXP-05 is a weakness the README acknowledges in the results note, alongside shared geometry and the absence of an unseen-layout evaluation. Erasing three things at once means you cannot attribute the effect to any one of them, and the project says so rather than leaving it for a reader to discover.

## What the 84 reference runs actually show

The repository includes 84 executed runs, seven conditions by 12 fixed seeds, and the complete per-seed metrics are in data/benchmarks/reference.json. That is a small dataset and the project treats it as such.

The headline numbers are specific. The default controller and the frozen-readout control both complete an average of 5.00 returns. Silencing the left antenna lowers that to 2.00. Removing the steering prior lowers it to 0.42.

The interpretation the README offers is worth quoting in spirit: these results show that the engineered prior is a major contributor in this arena, and they do not establish a food-return advantage from learning. The stated point is that the experiment reveals which mechanism matters, instead of treating movement or changing weights as proof of learned intelligence.

That is an unusually sober reading of a result that could easily have been presented the other way round. A frozen readout performing identically to a learning one is the kind of number that gets quietly dropped in a less careful write-up. Here it is the central finding, and it is the one that argues for the existence of EXP-04 in the first place.

The comparison also has a scope limit that the results note describes: the same arena geometry is shared across conditions, the memory experiment is a composite intervention, and there is no evaluation on an unseen layout. Those three caveats are the reasons the numbers cannot be generalised, and the project states them.

For a reader evaluating whether the model learns anything at all, the honest answer from this repository is that on this arena, with this scaffold, it does not show a food-return advantage from learning.

## Running the protocols yourself, and rebuilding the single file

The command line side is the part a researcher actually uses, and it is driven by the npm scripts declared in package.json. With Node.js 22 or later:

```bash
npm test
npm run experiment -- --protocol antenna --seed 17
npm run benchmark
npm run replay -- --file data/runs/relocation-seed17.json
npm run build
```

npm test runs the node test runner over tests/*.test.mjs. npm run experiment maps to scripts/run-experiment.mjs, benchmark to scripts/benchmark.mjs, replay to scripts/replay.mjs, and the final command, npm run build, runs scripts/build-standalone.mjs and rebuilds the standalone HTML from the source.

That last command is the one that closes the loop on the delivery format. The single-file artefact is not a hand-maintained file, it is generated, and the build is reproducible.

There is more in the package.json than the README mentions. A market script runs scripts/run-market.mjs, which backs the external tasks surface, and a verify script runs scripts/verify-package.mjs. The repository also ships MANIFEST.sha256 at the root, which is how the standalone file's contents are checked, along with a CITATION.cff and a SECURITY.md.

The README makes a claim about dependencies that is worth checking against the manifest, because it is unusual: the application, tests, simulation and command-line experiments have no third-party runtime dependencies. Figure regeneration is called out as an optional separate workflow, which is scripts/render-figures.mjs, and it is the one part likely to need more than the standard library.

The project has no GitHub releases, and the last push was on 2026-09-12, with the licence set to MIT in package.json and a LICENSE file at the root.

## Conclusion

Adopt ANT-1 if you want to teach or study embodied control with something you can open and interrupt, since the whole point of the repository is that you can silence a sensor, freeze the readout or erase the memory vector and watch what changes, and the 84 reference runs are included so the comparison is repeatable. Do not adopt it as evidence about animals or about learning in general, because the README states the network is a compact synthetic model whose units and connections are not taken from an ant connectome, and that the results do not establish a food-return advantage from learning. Before you draw conclusions, read docs/RESULTS.md for the stated limits, including shared geometry and the absence of an unseen-layout evaluation, and note that the repository has no GitHub releases, the last push was on 2026-09-12, and the licence is MIT.

## FAQ

### What is ANT-1 and what does it simulate?

ANT-1 is an open laboratory connecting an ant-inspired body to a synthetic neural controller. A single simulated ant explores a 2D arena, finds an odour source, records a food-location vector and returns to its nest, driven by a 12 input, 32 recurrent unit network with 5 actions.

### How do I run ANT-1 without installing anything?

Download or clone the repository and double-click ANT-1.html, which is a self-contained edition embedding the application and its reference runs. No Python, Node.js, API key, account or internet connection is needed for the laboratory itself.

### What experiments can I run in ANT-1 and how long is each one?

There are seven protocols, EXP-01 through EXP-07, covering navigation, relocation, silencing the left antenna, a frozen readout, a composite memory erase, clamping recurrent units 00 to 07, and removing the steering prior. Each protocol lasts 2,400 steps, about 240 simulated seconds, with the intervention at step 1,000.

### What do the ANT-1 reference results actually show?

Across 84 executed runs, seven conditions by 12 fixed seeds, the default controller and the frozen-readout control both average 5.00 returns, silencing the left antenna lowers that to 2.00, and removing the steering prior lowers it to 0.42. The README says this shows the engineered prior is a major contributor and does not establish a food-return advantage from learning.

### How do I reproduce an ANT-1 experiment from the command line?

With Node.js 22 or later, use npm run experiment with a protocol and seed, for example npm run experiment -- --protocol antenna --seed 17. Other scripts are npm test, npm run benchmark, npm run replay with a file path, and npm run build, which rebuilds the standalone HTML from the source.

### Is ANT-1 a model of real ant behaviour?

No. The README states the network is a compact synthetic model and that its units and connections are not taken from an ant connectome. The documentation images are described as model figures, not browser screenshots or biological recordings.

## Sources

- [ashleyotooligan/ant-1 on GitHub](https://github.com/ashleyotooligan/ant-1)
- [Issues](https://github.com/ashleyotooligan/ant-1/issues)
- [License: MIT](https://github.com/ashleyotooligan/ant-1/blob/main/LICENSE)
- [README](https://github.com/ashleyotooligan/ant-1/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ashleyotooligan-ant-1