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

⚙️ Prerequisites

Before starting, make sure you have:

• Codex CLI installed (brew install --cask codex or npm 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

✅ Effective Prompting Tips for Codex

📁 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.