pgntools

Standalone PGN utilities for chess, built on python-chess and Stockfish. Tools chain together: build a repertoire from many games, evaluate it, weigh the branches for a trainer, and trace tree lines back to their source games.

Install

pip install pgntools

That gives you a pgntools command with one subcommand per tool, plus a short command per tool:

pgntools --help              # lists every tool
pgntools findseq --help      # a tool's own arguments
pgn-findseq --help           # the same tool, short form

python -m pgntools.<tool> works as well and always has — the three routes run the same code.

Stockfish is not installed by pip. annotate and playchance need the binary on the machine; the other four tools never touch an engine. Install it from your package manager or from stockfishchess.org, then point the tools at it:

pgntools annotate -f repertoire.pgn --engine /path/to/stockfish   # explicit, per run
export STOCKFISH_PATH=/path/to/stockfish                          # or for the whole shell

With neither given, the tools look for a stockfish on your $PATH.

Tools

Usage

pgntools repertoire -f capablanca_all.pgn -t 2 --counts --min-games 10 -o capablanca.repertoire.pgn
pgntools annotate   -f capablanca.repertoire.pgn -d 25 -s 60
pgntools playchance -f capablanca.repertoire.pgn -d 25 -s 60 --side black
pgntools glyphs     -f game.analysed.full.pgn
pgntools gamequery  -f capablanca_all.pgn -t capablanca.repertoire.pgn -l "e4 e5 Nf3"
pgntools findseq    -f capablanca_all.pgn -q "Be2 Bd7; Be3 e6"

Every tool takes its input with -f/--pgnfile and writes an output path derived from the input unless -o/--output says otherwise. Full argument tables and implementation notes live in .claude/rules/pgntools-<tool>.md in the repository.

Working on pgntools

git clone https://github.com/pgntools/pgntools.git
cd pgntools
python -m venv venv && venv/bin/pip install -r requirements.txt
venv/bin/python -m unittest discover -s tests -t .           # the full suite
venv/bin/python -m pgntools.repertoire -f pgns/capablanca_all.pgn   # a tool, uninstalled

Engine-dependent tests skip themselves when no Stockfish binary is found. pip install -e . additionally puts the pgntools and pgn-<tool> commands on your PATH from the checkout.

License

MIT — see LICENSE.