ChatAndChess

English | Deutsch

Terminal chess for local games, a built-in Minimax bot, Claude API mode, and Claude Code worker integration.
Terminal-Schach für lokale Partien, Minimax-Bot, Claude API und Claude-Code-Integration.

1. Screenshots & Terminal Preview
2. Architecture & Dataflow
3. Worker IPC Protocol Sequence
4. Features
5. Target Personas & Use Cases
6. Comparison Matrix
7. Requirements
8. Quick Start
9. How to Play
10. Tactics Analyzer
11. Game State Export
12. Tests & Verification
13. Privacy, Security & Zero Egress
14. Project Structure
15. Community Docs & Attribution
16. License & Liability

    a   b   c   d   e   f   g   h
  +---+---+---+---+---+---+---+---+
8 | r | n | b | q | k | b | n | r | 8
  +---+---+---+---+---+---+---+---+
7 | p | p | p | p | p | p | p | p | 7
  +---+---+---+---+---+---+---+---+
6 | . | . | . | . | . | . | . | . | 6
  +---+---+---+---+---+---+---+---+
5 | . | . | . | . | . | . | . | . | 5
  +---+---+---+---+---+---+---+---+
4 | . | . | . | . | P | . | . | . | 4   [White: 1. e2e4]
  +---+---+---+---+---+---+---+---+
3 | . | . | . | . | . | . | . | . | 3
  +---+---+---+---+---+---+---+---+
2 | P | P | P | P | . | P | P | P | 2
  +---+---+---+---+---+---+---+---+
1 | R | N | B | Q | K | B | N | R | 1
  +---+---+---+---+---+---+---+---+
    a   b   c   d   e   f   g   h

  White: K=King Q=Queen R=Rook B=Bishop N=Knight P=Pawn
  Black: k=King q=Queen r=Rook b=Bishop n=Knight p=Pawn

graph TD
    User["Player / AI Agent"] --> UI["chess.py (CLI / Terminal UI)"]
    UI --> Engine["Rules & Move Generator (UCI)"]
    UI --> Modes{"Game Mode Selection"}

    Modes -->|Hotseat| Local["2-Player Local"]
    Modes -->|Built-in Bot| Minimax["Minimax Engine + Alpha-Beta"]
    Modes -->|Claude API| API["Anthropic API (anthropic pkg)"]
    Modes -->|Claude Code| Worker["Worker IPC (chess_comm/*.json)"]

    Engine --> Analyzer["chess_analyze.py (Tactics Evaluator)"]

The file-based --worker mode decouples the game presentation from the calculation engine, enabling AI agents and CLI sub-processes to interact cleanly via discrete JSON state snapshots:

sequenceDiagram
    autonumber
    actor Player as Player / AI Agent
    participant CLI as Game Loop (chess.py)
    participant FS as IPC Channel (chess_comm/)
    participant Worker as Worker (chess.py --worker)
    participant Bot as Minimax Engine

    Player->>CLI: Make move (e.g. e2e4)
    CLI->>CLI: Validate UCI move and update board
    CLI->>FS: Write chess_request.json (board, castling, en-passant)
    Worker->>FS: Detect request file and parse state
    Worker->>Bot: Calculate optimal response (alpha-beta search)
    Bot-->>Worker: Return best move (e.g. e7e5)
    Worker->>FS: Write chess_response.json (move, timestamp)
    Worker->>FS: Delete chess_request.json
    CLI->>FS: Read chess_response.json and apply move
    CLI->>Player: Render updated board in terminal

• 4 Game Modes
  • 2 Player: Local hotseat game on one machine.
  • vs Bot: Built-in Minimax engine with configurable search depth (1–5).
  • vs Claude API: Optional game against Claude via the Anthropic API.
  • vs Claude Code: File-based worker communication for AI agents with persistent castling and en-passant state in worker JSON payloads.
• Full Chess Rules
  • Short and long castling, en passant captures, pawn promotion with piece selection, check detection, checkmate, and stalemate.
• Engine Hints
  • Equal hints (both sides), Engine mode (AI only), Training mode (human only), or Off (human mode).
• Tactics & Position Analysis
  • Piece-square positional heuristics, Alpha-Beta pruning, and a standalone tactics evaluator (chess_analyze.py).
• Standardized Export Formats
  • Direct conversion to FEN strings and structured chatandchess-game-v1.json export compatible with EXPORTFORMAT.md.

• Python 3.10+
• Zero external dependencies for base terminal game
• Optional: anthropic package for Claude API mode (pip install -r requirements.txt)

pip install -r requirements.txt

# Start game
python chess.py

# Windows launcher
START_CHESS.bat

# Worker mode for Claude Code / AI agents
python chess.py --worker

Moves use standard UCI notation: e2e4 (from-square to-square).

• Normal moves: e2e4, g1f3
• Castling: e1g1 (short) or e1c1 (long)
• Pawn promotion: Prompted automatically when reaching the 8th (or 1st) rank, e.g. e7e8q

# Analyze current position
python chess_analyze.py

# Custom search depth (e.g. depth 4)
python chess_analyze.py --depth 4

# Analyze a specific move sequence
python chess_analyze.py e2e4 e7e5 g1f3

# Show top 8 candidate moves
python chess_analyze.py --top 8

ChatAndChess implements standardized game exports documented in EXPORTFORMAT.md:

• FEN Format: Generated via chess.board_to_fen() for seamless interoperability with Lichess, Chess.com, and analysis tools.
• Application JSON: chatandchess-game-v1.json generated via chess.build_game_export() capturing full game history, active mode, and board state without cloud dependency.

The test suite covers move generation, castling rights, en-passant persistence, worker IPC payloads, export formatting, and platform smoke verification:

# Run unit test suite (27 tests)
python -m unittest discover -s tests -p "test_*.py"

# Python syntax compilation check
python -m py_compile chess.py chess_analyze.py

# Platform smoke test (worker boot, analyzer, quit)
python tests/source_platform_smoke.py

# Code style audit
ruff check .

ChatAndChess operates 100% locally by default. API keys belong in the ANTHROPIC_API_KEY environment variable or a local key file, never in this repository.

Ignored local files:

• .env, .env.*, .anthropic_key, credentials & tokens
• chess_settings.json
• CLAUDE_PROMPT.txt
• chess_comm/ (runtime worker directory)
• Build outputs (build/, dist/, *.exe, *.msi)
• Local database/cache outputs (*.db, .pytest_cache/, .ruff_cache/)

chess.py                  Main game (all modes, engine, rules, worker interface)
chess_analyze.py          Tactics analyzer (position evaluation, candidate moves)
pyproject.toml            PEP 621 package & test metadata
START_CHESS.bat           Windows launcher
build_exe.bat             Optional PyInstaller build helper for Windows
requirements.txt          Base / optional dependency notes
EXPORTFORMAT.md           Game export specification (FEN & JSON)
NOTICE                    Copyright & attribution notice
THIRD_PARTY_LICENSES.md   Level 1 SBOM & runtime invariants
tests/
  test_bugsweep_regressions.py  Rules & move generation regressions (10 tests)
  test_export.py                FEN & game export tests (5 tests)
  test_worker_state.py          Worker IPC roundtrip & castling tests (5 tests)
  source_platform_smoke.py      Platform smoke test
  test_metadata.py              Documentation & contract parity tests
README/screenshots/       Repository screenshots
chess_comm/               Runtime IPC communication directory (gitignored)
chess_settings.json       Local game settings (gitignored)

• Contributing
• Code of Conduct
• Security Policy
• Changelog
• LLM Context
• Attribution Notice
• Third-Party Licenses & SBOM

MIT License — Copyright (c) 2026 Lukas Geiger.

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gelten die Haftungsausschlüsse der MIT-Lizenz.

Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.

This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.