Caissa Codex

A free, ad-free reference of the 3,690 named chess opening lines in the Lichess chess-openings dataset, one page per line, with results from Lichess games.

Live: https://chesscodex.org

What's on the site

• An opening page for every named line: the moves on an interactive board, where the line sits in the opening tree, its variations and the lines one move away by another move order, the moves played next with their Lichess results, results by rating band and in master games, and a PGN download.
• Descriptions of the 50 most popular openings (history, ideas, main lines, strengths and weaknesses); other pages get an overview built from the data.
• Browse by name (A–Z), by ECO code, or by rankings built from Lichess games: the best openings for White and for Black (overall and by rating band), the most popular openings and the most popular gambits.
• Opening identifier: name the opening of a game from pasted moves, a PGN, moves played on a board, or a FEN.
• Practice a line from memory with spaced repetition, keep a repertoire for White and Black, or play on from any opening against Stockfish in the browser. Repertoire and practice progress stay in the browser.

Running it locally

Needs PHP 8.3+ with pdo_sqlite (on Windows, add -d extension=pdo_sqlite -d extension=sqlite3 to the php commands below).

git clone https://github.com/agent-carl/chesscodex.git && cd chesscodex
cp config.example.php config.php         # then read the comments in it
php tools/seed.php                       # creates db/chesscodex.sqlite from db/*.tsv
php -S 127.0.0.1:8099 -t . tools/dev/router.php

Open http://127.0.0.1:8099. tools/dev/router.php stands in for the nginx rules, so the same security headers and Content Security Policy apply locally.

Game statistics come from the Lichess Opening Explorer, which needs a personal API token (lichess_token in config.php, no scopes). Without one the pages work but show no statistics. Results by rating band and master games are fetched by a slow background job (tools/fetch-levels.php); please keep to one request at a time — the explorer allows about 20 a minute.

Checks

bash tools/check.sh      # PHP lint, unit tests, minified files, JS syntax

public/*.min.js and public/style.min.css are generated by php tools/minify.php (which check.sh runs); edit the sources, never the .min files. The same checks run on GitHub for every push.

How it's built

PHP 8.4, SQLite and plain JavaScript: no framework, no Composer packages, no npm and no bundler. In production it runs on a Raspberry Pi 5 (nginx, PHP-FPM) behind a Cloudflare Tunnel; the server configuration is in deploy/.

Path	What
index.php	Front controller and route table
lib/	PHP classes: queries (Opening.php), handlers (Routes*.php), Lichess client and caches
templates/	Pages, wrapped by layout.php
public/	JavaScript and CSS (css/NN-*.css, joined in order)
db/	Source data (*.tsv), schema, descriptions (descriptions/*.md)
tools/	Seeding, minifying, background jobs, SEO checks, local dev server
tests/	Unit tests (php tests/run.php) and an HTTP smoke test
vendor/	chessground, chess.js, Stockfish, Parsedown

ARCHITECTURE.md walks through a request, the database, the caches and the reasons behind the main decisions.

Feedback

Every opening page has a form to suggest a description or report a mistake; issues on GitHub are welcome too.

License

Copyright (C) 2026 Ivan Petrov

Caissa Codex is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; see LICENSE for details.

If you run a modified copy as a website, the AGPL asks you to offer its users the source code of your version.

Third-party code in vendor/ keeps its own license: chessground and Stockfish (GPL-3.0), chess.js (BSD-2-Clause), Parsedown (MIT). The opening names and moves come from the Lichess chess-openings dataset (CC0).