Cody: The AI-Authored Chess Engine

Cody is an experimental chess engine where every line of code is generated by AI. The goal is to push LLM-assisted programming and answer one question: how strong of a chess engine can AI build from scratch?

� Support This Project

Every code improvement Cody makes requires AI API calls, which cost real money. While you can run Cody locally with free models like Ollama, the best results come from premium models like GPT-4 or Claude. If you find this experiment interesting or valuable, please consider supporting development costs.

Your contributions help keep Cody improving and experimenting with cutting-edge AI models. Every donation directly funds API usage and compute resources.

�🚀 Philosophy

Unlike traditional engines (like Stockfish) or NNUE-based engines tuned by humans, Cody is a "Zero-Human-Code" project.

• Architecture and logic: All search algorithms, evaluation functions, and bitboard manipulations are AI-generated.
• Debugging: Human intervention is limited to providing error logs back to the AI for self-correction.
• Goal: Achieve a competitive ELO rating with a codebase birthed from prompt engineering.

� Getting Started

First time here? Start with these resources:

1. README.md <- You are here (project overview)
2. ROADMAP.md - Current priorities and completed milestones
3. QUICKREF.md - Command cheatsheet while working
4. cody-graph/PHASES.md - Details on each orchestration phase
5. cody-graph/DIAGNOSTICS.md - Troubleshooting and logs
6. cody-graph/ELO_GAIN_PHASE.md - ELO loop details
7. architecture.md - Deep dive into design and implementation

For running the improvement orchestrator, see "Automated Improvement System" section below.

�🛠 Features (Current Status)

• Bitboard representation: High-performance board state management with PieceBitboards and occupancy maps.
• UCI protocol support: Works with standard chess GUIs like Arena, Cute Chess, or Scid vs. PC.
• Search algorithms:
  • Negamax with alpha-beta pruning.
  • Iterative deepening with time management.
  • Quiescence search to avoid the horizon effect.
  • Transposition table for move ordering and cutoff reduction.
• Evaluation: AI-crafted heuristics, including piece-square tables (PST) and material imbalance weights.
• Move generation: Pseudo-legal move generation with legality verification via attack checking.

🧠 How Cody Improves

Cody uses an automated multi-phase improvement loop powered by LangGraph orchestration:

Single-Phase (Current - Clippy Fixes)

1. Run clippy --W clippy::pedantic → Detect warnings
2. LLM proposes fix (unified diff)
3. Apply patch to disk
4. Verify (build + tests)
5. Commit on success or rollback on failure

Multi-Phase (Ready to Deploy)

Additional phases can be enabled in cody-agent/config.json:

• Clippy phase: Eliminate pedantic clippy warnings
• Refactoring phase: Improve code quality and architecture
• UCIfeatures phase: Implement missing UCI commands for tournament-grade protocol support
• Performance phase: Optimize critical paths for speed (uses o3 model)
• ELOGain phase: Chess-specific improvements to increase playing strength (uses o3 model)
• Unit Tests/Docs phase: Test coverage and documentation updates

🏗️ Architecture

The codebase is organized as a Cargo workspace with two crates:

• bitboard/ — Pure bitboard logic, move generation, position manipulation

  • Exports: Position, Move, MoveGen, bitboard utilities

• engine/ — Search engine, evaluation, UCI API, benchmarks

  • Depends on: bitboard (path dependency in Cargo.toml)
  • External dependencies: criterion (benchmarking), once_cell, rayon, crossbeam
  • Exports: UCI API, search algorithms, benchmark harness

Key constraints:

• Fixed-block allocator: Search nodes are preallocated in an arena, no heap allocations in hot path
• External dependencies: Allowed only when they are extremely high-performance and used in performance-critical paths
• Type safety: Semantic newtypes like Ply, Depth, NodeId to prevent type confusion
• Separation of concerns: Bitboard crate focuses on board rules; engine crate handles search/UCI

See architecture.md for detailed design.

🧪 Automated Improvement System (LangGraph)

Setup

Install dependencies:

pip install -U langgraph openai

Authenticate with OpenAI:

# Linux/macOS
export OPENAI_API_KEY="sk-..."

# Windows (PowerShell)
$env:OPENAI_API_KEY = "sk-..."

# Windows (cmd)
set OPENAI_API_KEY=sk-...

Configure in cody-agent/config.json:

{
   "model": "gpt-4-turbo",
   "models": {
      "clippy": "gpt-4-mini",
      "refactoring": "gpt-4-turbo",
      "features": "gpt-4-turbo",
      "performance": "gpt-4-turbo",
      "ELOGain": "gpt-4-turbo",
      "unit_tests_docs": "gpt-4-mini"
   },
   "use_local": false
}

Note on Model Names: The model names above are current defaults. Adjust them to match your OpenAI API availability. For complex optimization tasks (performance, ELOGain), use your most capable model. For simpler tasks (clippy), faster/cheaper models work well.

Configuration Fields Explained

• model: Default model (kept for future compatibility)
• models.<phase>: Per-phase model override
  • clippy: Fastest/cheapest model (fixing obvious warnings)
  • refactoring: General-purpose model (code quality improvements)
  • features: General-purpose model (new capabilities)
  • performance: Capable model (deep optimization analysis)
  • ELOGain: Capable model (chess-specific improvements)
  • unit_tests_docs: Faster/cheaper model (straightforward test generation)
• use_local: If true, use local Ollama instead of OpenAI API

Run the Orchestrator

From the repo root:

# Run all configured phases
python cody-graph/main.py all

# Run a single phase
python cody-graph/main.py clippy      # Fix compiler warnings
python cody-graph/main.py refactor    # Code quality improvements
python cody-graph/main.py features    # New features/UCI commands
python cody-graph/main.py performance # Speed optimization
python cody-graph/main.py elogain     # Chess ELO improvements
python cody-graph/main.py tests       # Test coverage & docs

Monitoring Orchestration Progress

The orchestrator logs diagnostic information to .cody_logs/ with timestamped files:

• *_clippy_output.txt — Compiler warnings detected
• *_llm_response.txt — LLM reasoning and proposed fixes
• *_diff_extracted.log — Applied patches
• *_build_output.txt — Build/test results

Check progress in real-time or review diagnostics afterward. See DIAGNOSTICS.md for detailed log reference.

This will:

1. Load configured phases from cody-agent/config.json
2. Execute phases sequentially (or run a single phase)
3. Generate diagnostics in .cody_logs/
4. Save progress to orchestrator_state.json

Optional environment variables:

# Linux/macOS
export CODY_REPO_PATH="/path/to/Cody"
export OPENAI_API_KEY="sk-..."

# Windows (PowerShell)
$env:CODY_REPO_PATH = "D:\Cody"
$env:OPENAI_API_KEY = "sk-..."

Documentation

• cody-graph/DIAGNOSTICS.md — Diagnostic output and troubleshooting
• cody-graph/PHASES.md — Multi-phase orchestration details

🔨 Building and Testing

Build:

cargo build --release

Run tests:

cargo test
cargo test -p bitboard
cargo test -p engine

Run benchmarks:

cargo bench -p engine

Run UCI engine:

cargo run -p engine

Validate move generation:

cargo run --release -p engine -- perft 5

Change Acceptance Criteria (ELO)

Use cody-graph/tools/selfplay.py to decide whether a code change should be accepted as an ELO improvement.

Prerequisites

1. cutechess-cli is installed at C:\Program Files (x86)\Cute Chess\cutechess-cli.exe.
2. Opening book exists at cody-graph/tools/weak.epd.
3. Python env is available (D:/Cody/.venv/Scripts/python.exe in this repo).

Baseline vs Candidate setup (release builds)

Run from repo root (D:\Cody):

# Build current commit as candidate
cargo build --release

# Keep a baseline executable in the same folder as cody.exe.
# Example: create baseline once from a known-good commit/tag, then copy it here as cody-vX.Y.exe.
Copy-Item .\target\release\cody.exe .\target\release\cody-v1.0.exe

selfplay.py expects:

• Candidate: target/release/cody.exe
• Baseline: highest versioned target/release/cody-v*.exe

Run reproducible A/B selfplay

Push-Location .\target\release
D:/Cody/.venv/Scripts/python.exe ../../cody-graph/tools/selfplay.py --mode strict
Pop-Location

If you are already in repo root (D:\Cody), use this equivalent command:

D:/Cody/.venv/Scripts/python.exe .\cody-graph\tools\selfplay.py --mode strict

../../cody-graph/tools/selfplay.py is only valid when current directory is target\release.

Strict mode pins deterministic settings (seed, threads, hash, sequential openings) and writes:

• target/release/temp_match.pgn
• target/release/temp_match.meta.json

Acceptance criteria for code changes

1. Build and tests pass:

• cargo build --release
• cargo test -p bitboard
• cargo test -p engine

2. Selfplay completes in --mode strict with no illegal move/disqualification.
3. Candidate score is better than baseline in the strict run (Score of Candidate vs Champion: W - L - D with W > L).
4. Keep temp_match.meta.json with the result so the comparison can be reproduced later.

If W <= L, treat the change as not yet proven and iterate.

📊 Current Capabilities

• Full legal move generation with proper castling and en passant handling
• Quiescence search to evaluate quiet positions accurately
• Transposition table for move ordering and cutoff reduction
• Time management with absolute and remaining time budgets
• UCI protocol for integration with chess GUIs

🎯 Playing Strength

Cody currently plays at about 2100, based on playing against weak engines: Simplex, Rebel and Minimal.

Version ELO increases

Engine	Elo Gain
Simplex	2373
Cody-2.0.0.0	2106
Rebel	1992
Minimal	1978
Cody-1.0.0.0	1865

🚀 Development Status

Completed:

• ✅ Complete bitboard infrastructure
• ✅ Legal move generation (pseudo-legal + legality check)
• ✅ UCI protocol handler
• ✅ Negamax search with alpha-beta pruning
• ✅ Quiescence search
• ✅ Transposition table
• ✅ Time management
• ✅ Automated clippy warning fixes

In Progress / Recently Completed:

• 🔄 Improving move ordering heuristics
• 🔄 Optimizing search performance
• ✅ Automated ELO improvement loop with SPRT testing and version management
• ✅ Multi-phase orchestration system for diverse improvement strategies
• ✅ Diagnostic logging with detailed LLM interaction tracking

Not Yet Implemented (Infrastructure Ready):

• ⏳ Refactoring phase (code quality — agent ready, decision criteria not finalized)
• ⏳ Additional UCI feature expansion (infrastructure ready, feature backlog pending)

Completed Phases:

• ✅ Clippy fixes — Automated compiler warning elimination
• ✅ ELO gain — Systematic chess engine strength improvements
• ✅ Unit test generation — Position-specific regression test creation

📝 License

MIT License. See LICENSE for details.