Originally published on malcolmlow.net
A step-by-step walkthrough of using OpenAI's agentic coding tool to scaffold, solve, test, and visualise the classic Knight's Tour chess problem — entirely through natural language prompts.
This post assumes you have Codex CLI installed and authenticated. We'll be working in three phases, each driven by a carefully crafted Codex prompt.
♞ What is the Knight's Tour Problem?
The Knight's Tour is a classic puzzle from combinatorics and graph theory: given an n×n chessboard and a knight placed on any starting square, can the knight visit every square on the board exactly once using only valid knight moves? A knight moves in an L-shape — two squares in one direction and one square perpendicular, giving it up to eight possible moves from any position.
The problem has been studied for over a thousand years. Arab mathematicians documented it as early as the 9th century, and Leonhard Euler conducted a systematic mathematical analysis in 1759. There are two variants: an open tour, where the starting and ending squares differ, and a closed (re-entrant) tour, where the knight can return to its starting square in one move. On the standard 8×8 board, there are over 26 trillion distinct open tours.
From an algorithmic standpoint, the Knight's Tour is a special case of the Hamiltonian path problem on a graph, where each square is a node and edges connect squares reachable by a knight move. Finding a Hamiltonian path is NP-complete in general, but the regular structure of the chessboard makes efficient heuristics possible.
The most well-known heuristic is Warnsdorff's rule (H.C. von Warnsdorff, 1823): at each step, move to the unvisited square that has the fewest onward moves. This greedy approach runs in linear time relative to the number of squares and finds a tour almost always on boards of size 5×5 and above.
🗺️ What We're Building
| Phase | What Codex Builds | Output |
|---|---|---|
| Phase 1 | Core solver using Warnsdorff's heuristic | CLI app, ASCII board output |
| Phase 2 | Pytest test suite and colourised terminal output | ANSI colour board, passing tests |
| Phase 3 | Flask web app with animated HTML canvas | Interactive browser visualisation |
⚙️ Prerequisites
Before starting, make sure you have:
- Codex CLI installed (
brew install --cask codexornpm i -g @openai/codex) - Authenticated with a ChatGPT Plus/Pro account or an OpenAI API key
- Python 3.10+ available in your shell
- Git installed on your machine
📁 Project Setup
We'll use Git throughout this guide as a safety net. Configure your identity first if needed:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Create the project directory and initialise the repo:
mkdir knights-tour && cd knights-tour
git init
git commit --allow-empty -m "initial commit"
codex
Once the TUI loads, generate an AGENTS.md file first. It acts as a standing project-level system prompt — Codex reads it automatically at the start of every future session.
📝 Codex Prompt — Generate AGENTS.md
"Create an AGENTS.md file in the project root for a Python CLI and web application project. Include the following standing instructions: use Python 3.10+ with type hints throughout; place all tests in a /tests directory using pytest; never use global mutable state; prefer functions over classes unless OOP is genuinely the better fit; handle all CLI arguments with argparse; use Flask for any web routes; keep each module focused on a single responsibility."
Why prompt Codex to write AGENTS.md instead of writing it yourself? You describe your intent conversationally rather than worrying about format, and it sets the right mental model for the rest of the guide. You can update it at any time: "Add a rule that all functions must have docstrings" — Codex will edit the file in place.
Phase 1 — Core Solver
📝 Codex Prompt — Phase 1
"Create a Python CLI app that solves the Knight's Tour problem. Use Warnsdorff's heuristic: at each step, move to the unvisited square with the fewest onward moves. The board size and starting position (row, col) should be configurable via argparse with defaults of n=8, row=0, col=0. The solver should return None if no tour is found. Display the completed board as a grid of move numbers, right-aligned. Save the solver logic in knight_tour.py and the entry point in main.py. Include a requirements.txt and a .gitignore for Python."
Here's a simplified version of what the generated knight_tour.py looks like:
MOVES = [(2,1),(2,-1),(-2,1),(-2,-1),(1,2),(1,-2),(-1,2),(-1,-2)]
def get_neighbours(x, y, n, visited):
return [(x+dx, y+dy) for dx,dy in MOVES
if 0 <= x+dx < n and 0 <= y+dy < n
and not visited[x+dx][y+dy]]
def solve(n, start_x, start_y):
visited = [[False]*n for _ in range(n)]
board = [[-1]*n for _ in range(n)]
x, y = start_x, start_y
visited[x][y] = True
board[x][y] = 0
for move in range(1, n*n):
neighbours = get_neighbours(x, y, n, visited)
if not neighbours:
return None
x, y = min(neighbours,
key=lambda p: len(get_neighbours(p[0],p[1],n,visited)))
visited[x][y] = True
board[x][y] = move
return board
Run it to verify:
python3 main.py --size 8 --row 0 --col 0
💡 Approval Flow: In Codex's default Auto mode, press A to accept or R to reject each diff. If Codex proposes something you don't want, reject and follow up with a corrective prompt — it retains full context.
Phase 2 — Tests & Colourised Output
📝 Codex Prompt — Phase 2
"Now add two things. First, create a test suite in tests/test_knight_tour.py using pytest. Test that: (1) solve() returns a valid tour where every integer from 0 to n²−1 appears exactly once, (2) consecutive moves are a valid knight's move apart, (3) solve() returns None for n=2 which has no solution. Second, add a new function print_coloured_board() in knight_tour.py that uses ANSI escape codes to colour the board — alternate between a light and dark background for a chess-style pattern, with white text for the move numbers. Call it from main.py instead of format_board() when --colour flag is passed."
Key tests:
import pytest
from knight_tour import solve
def is_valid_knight_move(x1, y1, x2, y2):
dx, dy = abs(x2-x1), abs(y2-y1)
return (dx, dy) in {(1,2),(2,1)}
@pytest.mark.parametrize("n,r,c", [(5,0,0),(6,1,1),(8,0,0),(8,3,4)])
def test_valid_tour(n, r, c):
board = solve(n, r, c)
assert board is not None
flat = sorted(v for row in board for v in row)
assert flat == list(range(n*n))
def test_no_solution_n2():
assert solve(2, 0, 0) is None
Install pytest and run:
pip3 install pytest
pytest tests/ -v
python3 main.py --size 8 --colour
Phase 3 — Flask Web App with Animated Visualisation
📝 Codex Prompt — Phase 3
"Add a Flask web app in app.py. It needs two routes: GET / serves a single-page HTML form where users can input board size (5–10) and starting row/col. POST /solve accepts these inputs, runs the solver, and returns the board as JSON. The HTML page should also contain a JavaScript canvas visualisation that animates the knight's path one move at a time — draw the board as a grid, colour visited squares progressively, and draw a ♞ symbol on the current square. Add flask to requirements.txt."
The key backend endpoint:
from flask import Flask, request, jsonify, render_template_string
from knight_tour import solve
app = Flask(__name__)
@app.route("/solve", methods=["POST"])
def solve_tour():
data = request.get_json()
n, row, col = int(data.get("size",8)), int(data.get("row",0)), int(data.get("col",0))
if not (5 <= n <= 10):
return jsonify({"error": "Board size must be between 5 and 10"}), 400
board = solve(n, row, col)
if board is None:
return jsonify({"error": "No solution found"}), 422
return jsonify({"board": board, "n": n})
pip3 install flask
python3 app.py
# Visit http://localhost:5000
🔄 Iterating Further — More Prompt Ideas
| Goal | Follow-up Prompt |
|---|---|
| Speed comparison | "Add a backtracking solver as an alternative to Warnsdorff's. Add a --solver flag to switch between them, and time both with Python's timeit." |
| Export result | "Add a --export flag to main.py that saves the board as a CSV and a PNG using matplotlib, with the knight path drawn as a line." |
| User clicks board | "Update the web app so users click a cell on the canvas to set the starting position instead of using the form fields." |
| Code review | "Review the current codebase for edge cases, type annotation completeness, and any issues with input validation in app.py." |
✅ Effective Prompting Tips for Codex
| Tip | Why It Helps |
|---|---|
| Name your files explicitly | Codex won't guess at naming conventions — "save to knight_tour.py" prevents arbitrary filenames. |
| Specify what None/failure means | Without "return None if no tour is found," Codex might raise an exception instead. |
| Bundle related changes in one prompt | Codex handles multi-file tasks well when given in a single cohesive prompt. |
| Keep sessions alive for follow-ups | Staying in the same session means Codex retains full context — no re-explaining. |
| Use AGENTS.md for standing rules | Anything you'd say in every prompt belongs in AGENTS.md. It keeps prompts shorter and style consistent. |
📁 Final Project Structure
knights-tour/
├── AGENTS.md
├── .gitignore
├── requirements.txt ← flask
├── knight_tour.py ← solver + display logic
├── main.py ← CLI entry point
├── app.py ← Flask web app
└── tests/
└── test_knight_tour.py
The workflow rhythm: each Codex prompt builds on the last without re-explaining context, and AGENTS.md silently enforces project conventions. The three phases took roughly 15 minutes end-to-end, most of which was reviewing diffs and running tests rather than writing code.
The Knight's Tour is just the illustration. The same prompt-iterate-commit loop applies to any project — and the more you invest in a good AGENTS.md upfront, the more useful each Codex session becomes.
Top comments (0)