regact runs coding agents on games they have never seen. The agent (Claude Code, Codex, Alan Code, ...) gets an unknown game, a sandboxed workspace and a controlled way to play: it writes Python controllers, the framework runs them against the real game, and the agent reads back what happened. The agent, the game and the experiment protocol are separate, interchangeable parts, so the same setup compares agents, models and protocols. Every run is recorded and can be replayed in a viewer: watch some benchmark runs online.
![]() ARC-AGI-3 |
![]() PuzzleScript |
![]() Sokoban |
![]() Baba Is You |
![]() MiniGrid |
|
Each clip is the end of a solved run, all under the cwm protocol (Claude Sonnet 5.5 or Haiku 5.5).
problem= |
Game | Install |
|---|---|---|
arc_agi |
the ARC-AGI-3 games | make install-arc |
puzzlescript |
games from the PuzzleScript gallery, original engine (page) | Node, make install-puzzlescript |
babaisyou |
the campaign levels of Baba Is You, worlds 0-9 (page) | make install-babaisyou |
minigrid |
MiniGrid and BabyAI; problem=minigrid_cwm is a deterministic set (page) |
make install-minigrid |
sokoban |
packs of Boxoban levels (page) | nothing |
The level-based games share ARC's conventions: RESET is a game action, completing the last level wins, and efficiency is measured against an optimal player (ROAE), as ARC measures it against a human one (RHAE). See Environments.
The protocol decides what the agent is asked to produce and which framework commands it gets.
protocol= |
The agent |
|---|---|
vanilla |
reads its recorded experience, writes a controller and runs it in the real game (RunController), as often as its budget allows. |
cwm |
must first write a Code World Model that reproduces all its recorded experience (UpdateCodeWorldModel); every action of its controllers is then checked against the model's prediction, and a contradiction sends it back to modeling. |
Both protocols share the environment management, the dataset API, controller execution and the limits, so a comparison measures the effect of requiring a validated world model and nothing else. Controllers run in a separate process from a frozen copy of the agent's code, without access to the workspace, the recorded data or the network. With problem.lifecycle=single_instance the game stays live across controller calls; multi_instance resets it before each call. See Protocols, Managed execution and CWM.
agent= |
What it is |
|---|---|
claude |
the Claude Code CLI |
codex |
the Codex CLI |
alan |
Alan Code, also against open-weight models served through an OpenAI-compatible endpoint |
antigravity |
Google's Antigravity CLI (agy) |
scripted |
a deterministic backend for tests, no LLM |
The agent is independent of the protocol: any agent runs any protocol, with any model it supports. Setup for each: Agents.
Python 3.11 or 3.12.
python -m venv .venv && . .venv/bin/activate
make install # core framework + dev tooling (pinned)
make install-arc # then the games you need (see the table above)
make install-agents # Alan Code; the claude / codex / agy CLIs install separatelyThree diagnostics check the machine, each only for what you installed:
make doctor # python, agent CLIs, sandbox, game extras
make probe # does the OS sandbox actually confine here?
make agentcheck # do the installed agents launch, bare and sandboxed?A run is composed from config groups picked by name, plus fields overridden on the command line (config.yaml). Always pass protocol=vanilla or protocol=cwm.
# Inspect the workspace and prompt a run would get, without starting the agent (no cost):
make run ARGS="agent=claude problem=sokoban protocol=cwm dry_run=true"
# ARC-AGI-3 with Claude Code under cwm, one game:
make run ARGS="agent=claude problem=arc_agi 'problem.tasks=[ls20]' protocol=cwm problem.lifecycle=single_instance limits.max_tool_calls=100"
# Baba Is You with Codex, plain acting:
make run ARGS="agent=codex problem=babaisyou protocol=vanilla limits.max_tool_calls=100 limits.max_seconds_per_task=3600"The main budgets are limits.max_tool_calls, limits.max_seconds_per_task and limits.max_actions_per_task. A launch stops with make stop RUN_DIR=<run dir> and continues with resume=<run dir>; a backend usage limit ends the task in a resumable state. See Experiments.
make viz EXP=experiments # then open http://localhost:8030Browse the experiments and benchmarks, follow an agent's conversation and tool calls, replay the real trajectory of each controller frame by frame (with the world model's accepted versions and mispredictions under cwm), and compare the runs of a benchmark side by side.
| Replay | Conversation |
|---|---|
![]() |
![]() |
| Benchmark runs | Benchmark graphs |
![]() |
![]() |
python -m regact.viz.export writes a static, read-only copy of the viewer for a website (Public viewer).
| Guide | What it covers |
|---|---|
| Overview | Architecture, extension points and code map |
| Protocols | The protocols, lifecycle, adding a protocol |
| Managed execution | Controllers, resets, the dataset API and the shared parameters |
| CWM | Modeling, validation, exploration and planning under cwm |
| Environments | The games, grid games, adding a game |
| Agents | Using and adding an agent |
| Experiments | Launching, stopping and resuming runs, outputs, HPC |
| Sandboxing | How isolation works and how it is verified |
| Public viewer | Exporting the viewer as a static site |
make check # ruff + mypy + unit tests
make test-all # every test, including the live ones (needs alancode / a game)







