Codenames PDF Generator

Generates a printable A4 landscape PDF for a one-team (blue) Codenames game. The PDF contains two pages:

1. Player card — 5×5 grid of words, no roles shown
2. Solution card — same grid with color-coded roles and a legend

Role distribution

Default distribution (configurable via --n_blue and --n_assassin):

Role	Count	Color
Blue	10	Blue
Neutral	15	Beige
Assassin	1	Black

Neutral cards fill the remaining slots automatically (25 − blue − assassin).

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Usage

Words can be passed directly as arguments or loaded from a file:

# Inline words (at least 25)
python main.py word1 word2 ... word25

# From a file (one word per line)
python main.py --words-file words.txt

# From a file with a custom delimiter
python main.py --words-file words.csv --delimiter ","

If more than 25 words are provided, 25 are chosen at random.

Options

Flag	Default	Description
--words-file FILE, -f FILE	—	Text file with one word per line
--delimiter DELIM, -d DELIM	—	Delimiter in --words-file instead of newlines (e.g. , or ;)
--output FILE, -o FILE	codenames.pdf	Output filename
--seed N, -s N	random	Seed for reproducible results
--n_blue N, -b N	10	Number of blue cards
--n_assassin N, -a N	1	Number of assassin/black cards
--no-shuffle	—	Keep words in their original grid order
--title TEXT	CODENAMES	Player card title (empty string disables it)

Example output

PDF generated with --seed 42 --title "CAMPUS RALLY"

Examples

# From a word file
python main.py --words-file words.txt

# Custom card counts
python main.py --words-file words.txt --n_blue 12 --n_assassin 2

# Fixed word order in the grid
python main.py --words-file words.txt --no-shuffle --seed 42

# Large word pool – 25 are picked randomly
python main.py --words-file big_pool.txt --seed 7 --output game.pdf

# Custom title
python main.py --words-file words.txt --title "CAMPUS RALLY"

# No title
python main.py --words-file words.txt --title ""