AAO-SH/codex-arena

**Your agent can learn a better way to work.** Codex Arena compares strategies in tournaments and turns winning methods into playbooks: practical guides with automations that Codex can reuse in your project. Before you activate them, it measures results on unseen tasks.
Why use it
- **Find methods that work again.** Compare quality, time, and resource use on recurring tasks.
- **Carry what you learn into the next job.** Reuse instructions, scripts, and checks in playbooks.
- **Keep spending under control.** Plan the competition and set limits before running it.
- **Keep knowledge in the project.** Consult local memory, evidence, and history when you need them.
Get started in your project
Open the folder where you want to use Arena and ask Codex:
Installation is local to the project and does not start a competition. You choose the folder; there is no required path.
Prefer the terminal? Install with npm, PyPI, or GitHub
Requires **Python 3.11+**. npm is an alternative way to run the Python installer; it also requires **Node.js 22+**. Run the commands from the workspace you want to use. --workspace . means “this folder”; you can omit the option or provide any relative or absolute path in quotes.
npm
PyPI
With uv, run it without installing the command globally:
Or install the command in a Python environment of your choice:
> The npm and PyPI packages are available. Package badges show registry-reported versions and download statistics.
From GitHub
In the folder where you want to keep the Arena code:
Run the installer and point it to your project folder, wherever it is:
The path above is just a relative example. The installer creates the destination if needed, copies the skill to .agents/skills/codex-arena, preserves existing configuration, and adds its configuration block to .codex/config.toml. --bootstrap prepares .venv with pinned dependencies.
Verify the installation
Open a terminal in the installed project folder.
**Windows / PowerShell:**
**Linux / macOS:**
To roll back the installation, run the installer from the clone or package with install --rollback --workspace "path/to/workspace". See Installation and recovery and npm/PyPI distribution.
From competition to playbook
**Compare → learn → validate → reuse.** Choose a task family, put different approaches to the test, and bring approved methods into your everyday work.
Compare strategies, models, and reasoning efforts
A tournament has three stages plus an additional validation step:
| Stage | What happens |
|---|---|
| Battle Royal | Everyone competes; scores place participants into tiers. |
| Swiss | Each tier competes for spots in the final. |
| Double elimination | Ten-game series determine each tier's champion, with a second-chance round. |
| +1 validation | Each playbook is compared with a run without a playbook on unseen cases. |
The four tiers are **iron, copper, silver, and gold**. Arena distinguishes task failures, quality-based losses, and ties. Models and reasoning efforts must be compatible with the environment's catalog; the policy remains fixed throughout the campaign. Rules, rubric, and scoring →
Use Arena for recurring tasks with observable criteria, such as validating JSON contracts or comparing development workflows with objective tests. A simple one-off task without criteria or reserved cases rarely warrants a tournament.
Try a demo without paid inference
In a repository clone, prepare the environment:
Activate it with .venv\Scripts\Activate.ps1 in PowerShell or source .venv/bin/activate on Linux/macOS. Then: