If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/official-stockfish/Stockfish shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5d ago
• 27+ active contributors
• Distributed ownership (top contributor 20% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live official-stockfish/Stockfish repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/official-stockfish/Stockfish.

What it runs against: a local clone of official-stockfish/Stockfish — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in official-stockfish/Stockfish | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of official-stockfish/Stockfish. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/official-stockfish/Stockfish.git
#   cd Stockfish
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of official-stockfish/Stockfish and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "official-stockfish/Stockfish(\\.git)?\\b" \\
  && ok "origin remote is official-stockfish/Stockfish" \\
  || miss "origin remote is not official-stockfish/Stockfish (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.cpp" \\
  && ok "src/main.cpp" \\
  || miss "missing critical file: src/main.cpp"
test -f "src/search.cpp" \\
  && ok "src/search.cpp" \\
  || miss "missing critical file: src/search.cpp"
test -f "src/nnue/network.cpp" \\
  && ok "src/nnue/network.cpp" \\
  || miss "missing critical file: src/nnue/network.cpp"
test -f "src/position.cpp" \\
  && ok "src/position.cpp" \\
  || miss "missing critical file: src/position.cpp"
test -f "src/engine.cpp" \\
  && ok "src/engine.cpp" \\
  || miss "missing critical file: src/engine.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/official-stockfish/Stockfish"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Stockfish is a free, open-source UCI chess engine written in C++ that analyzes chess positions and computes optimal moves using advanced search algorithms and neural network evaluation (NNUE). It is one of the strongest chess engines available and serves as the backbone for chess analysis in thousands of GUIs and online platforms worldwide. Single-binary monolith: src/main.cpp is the entry point, src/engine.cpp handles UCI protocol communication, src/search.cpp (implied) drives the move search algorithm, src/evaluate.cpp performs position evaluation, src/bitboard.h/cpp provides 64-bit board representation, and src/movegen.cpp generates legal moves. The embedded NNUE neural network (via incbin/incbin.h) is compiled directly into the binary.

Chess enthusiasts, GUI developers (who integrate Stockfish via UCI protocol), competitive chess players using analysis tools, and chess engine researchers studying move evaluation, search optimization, and neural network-based evaluation functions.

Highly mature and production-ready. The codebase is ancient (derived from Glaurung 2.1), actively developed with multiple GitHub workflows (CI/CD across ARM, AVX2, macOS, Windows), comprehensive testing infrastructure (tests.yml, sanitizers.yml, games.yml), and active community contributions via Fishtest. Clear governance with AUTHORS file and CONTRIBUTING.md guide.

Very low risk. The project is stable with no single-maintainer dependency (official Stockfish organization). However, the codebase is performance-sensitive C++ (~800k lines) where compiler-specific optimizations matter, and the NNUE neural network file (.nnue extension) is a build-time dependency that must be present. Breaking changes are rare but documented in the Discord community.

Active development focused on search optimization and neural network improvements. CI workflows test compilation across ARM (arm_compilation.yml), AVX2 compilers (avx2_compilers.yml), code quality (clang-format.yml, iwyu.yml, codeql.yml), and competitive strength (games.yml via Fishtest integration). Recent infrastructure includes matetrack.yml (endgame verification) and universal_compilation.yml.

git clone https://github.com/official-stockfish/Stockfish.git
cd Stockfish/src
make build ARCH=x86-64  # or ARCH=x86-64-modern for AVX2 support
./stockfish  # interactive UCI shell

Daily commands:

cd Stockfish/src
./stockfish
uci                    # Initialize UCI protocol
position startpos
go depth 20            # Search 20 plies deep

• src/main.cpp — Entry point that initializes the UCI engine and processes commands; every contributor must understand the command loop architecture.
• src/search.cpp — Core alpha-beta search algorithm with move ordering and pruning; the algorithmic heart of the engine that all strength improvements target.
• src/nnue/network.cpp — Neural network evaluation interface that loads and evaluates board positions; critical for understanding modern position evaluation.
• src/position.cpp — Board representation and move validation; foundational data structure used by every other component.
• src/engine.cpp — High-level engine orchestration between search, evaluation, and time management; coordinates the overall analysis pipeline.
• src/movegen.cpp — Legal move generation for all piece types; performance-critical function called millions of times per search.
• src/uci.cpp — UCI protocol parser and command handler; required for understanding how external GUIs communicate with the engine.

Implement a new evaluation heuristic in search

1. Add evaluation constant or flag in src/types.h or src/search.h (src/search.h)
2. Modify the search function to call new evaluation at relevant cutoff points (src/search.cpp)
3. If using position-specific data, extend src/history.h with new history table (src/history.h)
4. Test the change with src/benchmark.cpp to measure performance impact (src/benchmark.cpp)

Add a new UCI option (e.g., tunable parameter)

1. Register option in src/ucioption.cpp with default value and range (src/ucioption.cpp)
2. Add corresponding field to Options struct (declared in src/ucioption.h) (src/ucioption.h)
3. Use the option value in src/search.cpp or src/evaluate.cpp based on its purpose (src/search.cpp)
4. Document the option and its effect; test with src/benchmark.cpp (src/benchmark.cpp)

Optimize move generation or move ordering

1. For move generation: modify generation loops in src/movegen.cpp (src/movegen.cpp)
2. For move ordering: update scoring in src/movepick.cpp (src/movepick.cpp)
3. Consider adding or modifying history tables in src/history.h (src/history.h)
4. Validate correctness with perft test (tests/perft.sh) and benchmark impact (tests/perft.sh)

Improve position evaluation or add special case handling

1. For NNUE integration issues: check src/nnue/network.cpp and accumulator updates (src/nnue/network.cpp)
2. For special positions (checkmate, stalemate): add logic to src/evaluate.cpp (src/evaluate.cpp)
3. For position-specific knowledge: extend features in src/nnue/features/ or use src/position.cpp queries (src/position.cpp)
4. Run comprehensive tests to ensure no regressions in src/search.cpp behavior (src/search.cpp)

• Bitboards (64-bit integers) for board representation — Enables fast square queries, sliding piece attacks, and efficient move generation via bit operations
• NNUE (Efficiently Updatable Neural Networks) — Provides superior position evaluation vs hand-crafted heuristics while remaining fast enough for millions of evals/sec via incremental accumulator updates
• Alpha-beta search with transposition tables — Fundamental algorithm for game tree search; transposition table caches repeated positions to avoid redundant evaluation
• UCI protocol (text-based socket communication) — Standard interface allowing any GUI to communicate with the engine via stdin/stdout; decouples engine from UI
• Multi-threaded SMP (Symmetric Multi-Processing) — Scales search across multiple CPU cores for better throughput with work-sharing and shared transposition table

• NNUE evaluation replaces traditional hand-tuned evaluation function

  • Why: Neural networks achieve higher strength but require a trained model file embedded at compile time
  • Consequence: Reduced parameter tuning work by humans but harder to debug evaluation errors; model must be periodically retrained via self-play

• Incremental move/unmove with bitboards over explicit copy of position

  • Why: Faster move generation and reduced memory pressure during deep searches
  • Consequence: More complex position update logic and higher risk of state corruption; requires careful validation

• Shared transposition table with lockless hashing over thread-local tables

  • Why: Maximizes cache hit rate and benefits from other threads' work without synchronization overhead
  • Consequence: Occasional race conditions on table overwrites; accepted as harmless since transposition table is non-critical

• Text-based UCI input/output over binary protocol

  • Why: Simplicity and human readability for debugging; universal compatibility with all GUIs
  • Consequence: Higher parsing overhead and latency than binary protocols; not suitable for real-time applications

• Does not include a graphical user interface; relies on external GUIs (Chess.com, Arena, Lichess, etc.) for display and input
• Not a chess database or opening book manager; users

1. The NNUE neural network file (.nnue) must exist at runtime or evaluation falls back to slow static evaluation—binary distributions embed it, but source builds may need manual download. 2) Makefile relies on compiler auto-detection (COMP variable); cross-compilation requires explicit ARCH and COMP flags or builds may silently use suboptimal settings. 3) Bitboard operations assume little-endian and 64-bit integers; 32-bit builds require different bitboard implementations (not modern focus). 4) UCI go command with depth/time parameters has subtle interaction with search termination; modify carefully. 5) The incbin.h header is used to embed binary files at compile-time; if you modify it, binary size changes significantly.

• UCI (Universal Chess Interface) — Stockfish communicates with all chess GUIs exclusively via UCI protocol (implemented in src/engine.cpp); understanding UCI command parsing is essential to modify engine behavior or debug I/O
• Bitboard Representation — Stockfish uses 64-bit integers as a compact board representation (src/bitboard.h); bitwise operations replace array lookups, making move generation and position evaluation orders of magnitude faster
• Magic Bitboards (Move Generation) — Stockfish uses magic number multiplication to compute sliding piece moves in O(1) time; this non-obvious optimization is core to movegen.cpp performance
• NNUE (Efficiently Updatable Neural Networks) — Stockfish's evaluation function uses NNUE instead of hand-crafted evaluation; the .nnue file is trained separately (nnue-pytorch) but embedded at compile-time (src/evaluate.cpp), representing a paradigm shift from traditional engines
• Alpha-Beta Pruning with Move Ordering — Stockfish implements alpha-beta search with sophisticated move ordering (src/movepick.cpp) to reduce branching factor; understanding move ordering heuristics is key to any search optimization
• Transposition Table (Hash Table for Positions) — Stockfish caches previously evaluated positions to avoid recomputation; not explicitly visible in file list but fundamental to src/search.cpp logic for avoiding redundant analysis
• Compile-Time Binary Embedding (incbin) — The NNUE neural network and other static data are embedded directly into the executable using incbin/incbin.h, eliminating external file dependencies and enabling portable single-file distribution

• lichess-org/lila — Lichess chess platform uses Stockfish as its primary analysis engine; integrates via UCI protocol
• glinscott/fishtest — Fishtest is the distributed testing framework for evaluating Stockfish candidate patches; direct integration point for this repo's development workflow
• Chess-Engines-and-Tools/Chess-Engine-Resources — Curated list of chess engines and tools; Stockfish is the reference engine in this ecosystem
• official-stockfish/nnue-pytorch — Official Stockfish NNUE neural network training repository; produces the .nnue files embedded in Stockfish binaries
• DisposableHeroesOfPythonland/better-exceptions — Not directly related; but Stockfish CI uses Python scripts (scripts/*.py) that could benefit from better error handling—useful learning reference

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for NNUE network components

The NNUE (Neural Network Utility Evaluation) subsystem in src/nnue/ contains critical neural network layers (affine_transform.h, clipped_relu.h, sqr_clipped_relu.h, nnue_accumulator.cpp) but there are no dedicated unit tests visible in the repo. Given that NNUE is central to Stockfish's evaluation accuracy, adding tests would catch regressions in forward pass computations, accumulator updates, and feature transformations across different CPU architectures (important given the arch-specific compilation workflows).

• [ ] Create src/nnue/tests/ directory structure
• [ ] Add unit tests for affine_transform.h covering sparse and dense input paths
• [ ] Add tests for nnue_accumulator.cpp refresh and update operations
• [ ] Add tests for activation layers (clipped_relu.h, sqr_clipped_relu.h)
• [ ] Integrate tests into existing .github/workflows/tests.yml
• [ ] Ensure tests run across arm, avx2, and universal compilation targets per existing CI matrices

Add automated performance regression detection for move generation

The movegen.cpp and movepick.cpp files are performance-critical paths in the engine, but there's no dedicated performance testing workflow. While games.yml exists for strength testing, there's no specific benchmark regression detection. This would prevent subtle performance regressions in move generation that could impact search speed across different hardware (ARM, x86, AVX2 variants covered in the CI matrix files).

• [ ] Create new GitHub workflow .github/workflows/performance_benchmark.yml
• [ ] Leverage existing src/benchmark.cpp/benchmark.h infrastructure
• [ ] Add specific benchmark tests for movegen.cpp hot paths and movepick.cpp ordering
• [ ] Compare benchmark results against baseline (previous release or main branch)
• [ ] Fail workflow if performance regression exceeds threshold (e.g., >2%)
• [ ] Run benchmarks across arm_matrix.json, universal_matrix.json, and windows_arm_matrix.json configurations

Add integration tests for UCI protocol compliance in src/engine.cpp

The engine.cpp/engine.h files implement UCI protocol handling but there are no visible integration tests validating UCI command parsing and responses. Given Stockfish's role as a reference UCI implementation, adding tests would ensure commands like 'position', 'go', 'setoption' are correctly handled, especially important for maintaining compatibility as the NNUE architecture evolves.

• [ ] Create src/tests/uci_integration_test.cpp
• [ ] Add test cases for standard UCI commands: 'uci', 'isready', 'setoption', 'position', 'go', 'stop', 'quit'
• [ ] Test edge cases like malformed positions, invalid time controls, concurrent commands
• [ ] Add tests for NNUE-specific options that can be set via 'setoption'
• [ ] Create helper utilities for UCI protocol test harness
• [ ] Integrate into .github/workflows/tests.yml

• Add documentation comments to src/bitboard.h explaining the magic bitboard multiplier constants and their purpose—critical for new contributors but currently undocumented.
• Implement unit tests for edge cases in src/movegen.cpp (e.g., en passant capture validation, castling rights preservation) that are not covered in current test suite visible in tests.yml.
• Create a Python script in scripts/ to validate that a compiled binary's search behavior matches expected benchmarks from src/benchmark.cpp across ARCH variants (x86-64, x86-64-modern, ARM); useful for CI sanity checks.

Stockfish is a well-maintained open-source chess engine with generally good security posture. No critical vulnerabilities or hardcoded secrets were identified. The primary concerns are typical for C++ game engines: potential buffer overflows in array operations, external file validation for neural network weights, integer overflow in scoring calculations, and thread synchronization in shared memory operations. These are all low-severity concerns mitigated by the project's active maintenance, code review processes, and focus on correctness. No dependency vulnerabilities, injection risks, or infrastructure misconfigurations were detected based on the provided file structure. The codebase demonstrates mature security practices with GitHub Actions security workflows (CodeQL, sanitizers) already in place.

• Low · Potential Buffer Overflow in NNUE Network Processing — src/nnue/layers/affine_transform.h, src/nnue/layers/clipped_relu.h. The NNUE neural network layers (affine_transform.h, clipped_relu.h) perform mathematical operations on arrays without explicit bounds checking visible in the file structure. Chess engines typically process fixed-size boards (64 squares), but custom network architectures could introduce risks if input validation is insufficient. Fix: Review array access patterns in neural network layer implementations. Ensure all array accesses are bounds-checked and that input dimensions are validated against expected architecture specifications.
• Low · External Network File Loading Without Validation — src/nnue/network.cpp, src/nnue/nnue_misc.cpp. The NNUE network file loading mechanism (src/nnue/network.cpp, src/nnue/nnue_misc.cpp) reads neural network weights from external files. If the file format validation is insufficient, malformed or malicious network files could potentially cause crashes or unexpected behavior. Fix: Implement strict validation of NNUE network file format, including magic numbers, version checks, size bounds, and checksum verification. Reject any files that don't match expected specifications.
• Low · Potential Integer Overflow in Move Generation — src/movegen.cpp, src/movepick.cpp, src/evaluate.cpp. The movegen.cpp and movepick.cpp files perform calculations on move scores and positions. If evaluation scores or move counts exceed expected integer ranges, overflow conditions could theoretically occur. Fix: Use safe integer arithmetic libraries or add explicit range checks for score calculations. Ensure score values remain within defined bounds throughout the evaluation pipeline.
• Low · Shared Memory Implementation on Linux May Have Race Conditions — src/shm.h, src/shm_linux.h, src/thread.cpp. The shm_linux.h and shm.h files implement shared memory functionality for multi-threaded analysis. Insufficient synchronization primitives could lead to race conditions when multiple threads access shared game state. Fix: Review synchronization mechanisms (mutexes, atomics) in shared memory operations. Ensure all concurrent access to shared state is properly protected with adequate locking primitives.
• Low · Missing Input Validation on UCI Protocol Commands — src/engine.cpp, src/main.cpp. The engine.cpp file implements UCI (Universal Chess Interface) protocol handling. Malformed or unexpectedly long UCI commands could potentially cause issues if input validation is incomplete. Fix: Validate all UCI protocol inputs: enforce maximum command lengths, validate position FEN strings, sanitize move notation, and reject malformed commands gracefully.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.