Play command-line chess against either:

• Stockfish at fixed strength, with a local rating estimate.
• A built-in alpha-beta engine with heuristic evaluation.

The internal engine uses a Rust search backend automatically when the extension module is available, with a Python fallback for unsupported edge-case positions.

brew install stockfish uv sync

uv run chess

Useful options:

uv run chess --engine-elo 1400 --movetime-ms 200 --color white uv run chess --engine internal --depth 4 --movetime-ms 200 --show-search uv run chess --engine internal --benchmark-internal --movetime-ms 30 uv run chess --engine internal --benchmark-internal --movetime-ms 100 --benchmark-max-plies 160 uv run chess --engine internal --benchmark-internal --movetime-ms 200 --benchmark-stockfish-movetime-ms 100 uv run chess --engine internal --benchmark-internal --benchmark-anchor-center 2100 uv run chess --engine internal --show-engine-rating uv run chess --show-rating uv run chess --reset-rating

Use a dedicated Lichess bot account. Create a fresh account, generate a bot-play token, and upgrade the account to bot status from the official Lichess Bot API docs: https://lichess.org/api#tag/Bot.

Start from the example config:

cp lichess-bot.example.toml lichess-bot.toml

Then set the token and username in lichess-bot.toml, or override them with environment variables such as LICHESS_BOT_TOKEN and LICHESS_BOT_USERNAME.

Run the bot with:

uv run chess-bot uv run chess-bot --config lichess-bot.toml --log-level DEBUG

Defaults for v1:

• Standard chess only.
• Accepts blitz and rapid challenges by default.
• Uses the internal engine in uncapped time-limited mode (depth = 0) with a simple clock-aware move budget, a 250ms floor, and a 500ms fallback when clock data is missing.
• Writes per-game JSONL logs to lichess-games/.

Open the standalone decision viewer in a browser:

open decision-viz.html

Regenerate the data file behind it with either a fresh showcase game or a specific configuration:

uv run chess-viz --select-showcase uv run chess-viz --stockfish-elo 2200 --internal-color white --depth 7 --movetime-ms 100

• The rating is a local estimate, not a USCF/FIDE/site rating.
• Stockfish's UCI_Elo setting is approximate and depends on your hardware and time control.
• For the estimate to stay comparable, keep the same engine Elo and time control across games.
• Internal-engine games are rated on a separate track per search depth.
• Internal-engine ratings are only anchored after you benchmark that depth against Stockfish with --benchmark-internal.
• For the internal engine, --movetime-ms is a soft per-move time budget used alongside the configured depth target.
• --benchmark-max-plies lets long benchmark games finish instead of being forced into early draw caps.
• --benchmark-anchor-center lets you override the automatic Stockfish anchor range when recalibrating a stronger engine.
• --benchmark-stockfish-movetime-ms lets you benchmark asymmetric time controls; if omitted, both sides use the same per-move time.