🕵️ Codenames LLM Challenge

Welcome! This is a coding challenge where you build a guesser bot for the board game Codenames.

An LLM-powered spymaster will give you one-word clues. Your job is to write the guesser that picks the right words on the board.

How the game works

The board has 25 words split into hidden roles:

Role Count Meaning
🟥 RED 9 Your team's words — guess these!
🟦 BLUE 8 Opponent words — avoid these
💀 ASSASSIN 8 Instant loss if revealed

Each round:

  1. The spymaster gives a one-word clue + a number (e.g. "ocean 3")
  2. Your guesser can make up to number + 1 guesses
  3. A round ends when you reveal a BLUE word, reach the max guesses, or return None
  4. The game ends when all RED words are found (win) or the assassin is revealed (loss)

Your score is based on the number of rounds needed — fewer is better.

Two steps to participate

Step 1 — Clone the repository

Open a terminal and run:

git clone https://huggingface.co/spaces/LLM-course/codenames
cd codenames

Then set up the Python environment:

uv venv
source .venv/bin/activate        # on Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

(Optional but recommended) Pre-build the embedding cache so runs are faster:

python -m codenames.cli init-cache