AI Chess Bot

Terminal chess game with a custom rules engine and minimax AI. Play as white or black against four difficulty levels.

Demo

> py main.py

Welcome to Chess! Difficulty: Medium
You are white, the bot is black.

    a b c d e f g h
  8 ♜ ♞ ♝ ♛ ♚ ♝ ♞ ♜  8
  7 ♟ ♟ ♟ ♟ ♟ ♟ ♟ ♟  7
  6 · · · · · · · ·  6
  5 · · · · · · · ·  5
  4 · · · · · · · ·  4
  3 · · · · · · · ·  3
  2 ♙ ♙ ♙ ♙ ♙ ♙ ♙ ♙  2
  1 ♖ ♘ ♗ ♕ ♔ ♗ ♘ ♖  1
    a b c d e f g h

Turn: white (you)

white to move — enter move or command: e2e4

Full sample output: docs/demo.txt

Highlights

• Custom chess engine — no gameplay dependency on external chess libraries
• Negamax search with alpha-beta pruning and capture-first move ordering
• Position evaluation — material, piece-square tables, and check bonuses
• Full rules — castling, en passant, promotion, check/checkmate, stalemate
• Draw detection — 50-move rule, threefold repetition, insufficient material
• CLI features — unicode board, move log, undo, restart, JSON save/load
• Automated tests — rules, AI, persistence (15+ tests)

Quick start

Requirements: Python 3.10+ (stdlib only)

git clone https://github.com/Nicosmith43/Ai-Chess-Bot.git
cd Ai-Chess-Bot
py main.py

On Windows use py if python is not on your PATH.

Startup

1. Choose difficulty (1–4)
2. Choose color (w/b)

Commands

Input	Action
e2e4	Move (from + to square)
moves	Show move history
undo	Take back one ply
restart	New game
save [name]	Save to saves/
load [name]	Load from saves/
exit	Quit

Architecture

main.py
   └── Game (game.py)        — loop, commands, save/load, move log
         ├── Board (board.py) — rules, validation, draw detection
         ├── ChessBot (bot.py) — negamax + piece-square evaluation
         ├── UserInterface     — unicode board display, input
         └── persistence.py    — JSON save/load

Search flow: legal moves → order captures first → copy board → simulate → negamax(depth) → pick best move for bot color.

Tests

py -m unittest discover -s tests -v

CI runs on Python 3.11, 3.12, and 3.13 via GitHub Actions.

Project structure

Ai-Chess-Bot/
├── .github/workflows/ci.yml
├── docs/
│   ├── demo.txt
│   └── screenshot.png
├── main.py
├── saves/
├── src/
│   ├── board.py
│   ├── bot.py
│   ├── game.py
│   ├── persistence.py
│   └── user_interface.py
└── tests/
    ├── test_bot.py
    ├── test_game.py
    └── test_rules.py

License

MIT — see LICENSE.