openelo

CLI tool for managing chess engine rating lists. Register engines, configure rating lists, and automatically run round-robin tournaments using fastchess with Elo ratings calculated by ordo.

Prerequisites

• Node.js >= 20
• fastchess on PATH
• ordo on PATH

Installation

git clone https://github.com/jhonnold/openelo.git
cd openelo
npm install
npm run build
npm link   # makes `openelo` available globally

How It Works

openelo manages a pipeline from engine registration through to Elo ratings:

1. Engines — Register chess engine binaries with version labels
2. Rating Lists — Create lists that define tournament parameters (time control, variant, opening book, adjudication)
3. Enrollment — Add engines to a list; openelo generates all round-robin matchups automatically
4. Execution — openelo run feeds matchups to fastchess in batches, collecting PGN results
5. Ratings — After games complete, ordo calculates Elo ratings and produces snapshots

All state lives in ~/.openelo/ — a SQLite database, PGN files, and rating snapshots.

Usage

Setup

Initialize the workspace (creates ~/.openelo/ with database and directories):

openelo init

Register an engine with a version label:

openelo engine add stockfish /usr/bin/stockfish --version 17
openelo engine add lc0 /usr/bin/lc0 --version 0.31 --uci WeightsFile=/path/to/weights.pb

Adding a new version to an existing engine automatically triggers version replacement on all lists where it's enrolled:

openelo engine add stockfish /usr/bin/stockfish-new --version 18

Create a rating list (interactive prompts for variant, time control, opening book, adjudication):

openelo list create bullet-list

Other management commands:

Command	Description
openelo engine list	List all registered engines
openelo engine versions <name>	Show all versions of an engine
openelo engine remove <name>	Remove an engine (blocked if enrolled)
openelo list show <name>	Show list config, enrollments, progress
openelo list remove <name>	Soft-delete a list (data preserved on disk)

Running

Enroll engines in a list to generate round-robin matchups:

openelo enroll stockfish bullet-list
openelo enroll lc0 bullet-list

Run all pending batches (blocks until complete, handles SIGINT gracefully):

openelo run                      # all lists
openelo run bullet-list          # specific list
openelo run --concurrency 16     # limit system threads for engine concurrency

Remove an engine from a list (supersedes its matchups and re-rates):

openelo drop lc0 bullet-list

Check progress:

openelo status              # all lists
openelo status bullet-list  # specific list

Results

Force a rating calculation (normally happens automatically after run):

openelo rate bullet-list

View the latest ratings:

openelo ratings bullet-list

View historical snapshots:

openelo history bullet-list

Export PGNs, ratings CSV, and cross-table:

openelo export bullet-list

Development

npm run build       # Build with tsup -> dist/index.js
npm run dev         # Run via tsx (dev mode)
npm test            # Run all tests (vitest)
npm run test:watch  # Watch mode

Project Structure

src/
  index.ts          # Entry point
  cli.ts            # Commander setup, all command definitions
  db.ts             # SQLite connection, schema init
  types.ts          # Shared TypeScript interfaces
  workspace.ts      # File path utilities, directory creation
  lock.ts           # Mutual exclusion lock file
  engine.ts         # Engine CRUD operations
  list.ts           # Rating list CRUD operations
  enrollment.ts     # Enroll/drop + version replacement logic
  scheduler.ts      # Matchup + batch generation (round-robin)
  executor.ts       # Fastchess batch execution, PGN consolidation
  calibration.ts    # NPS benchmarking, TC scaling under concurrency
  rater.ts          # Ordo integration, snapshot management
  recovery.ts       # Crash recovery (RUNNING -> PENDING)
  runner.ts         # Execution loop, graceful shutdown, SIGINT
tests/              # One test file per module + integration tests