ChessCoach

ChessCoach is an iPhone chess-training app for adult beginners who want to reach club-level strength. It combines a structured curriculum, tactic puzzles, free position analysis, Stockfish-powered evaluation, and local LLM coaching.

The app uses a dark “Midnight Study” design language and is built as a SwiftUI/XcodeGen multi-target iOS project.

Features

• Learn — opening, middlegame, and endgame lessons with local progress tracking.
• Puzzles — interactive tactics with hints, feedback, ratings, and multi-move solutions.
• Play & Analyze — interactive board, FEN loading, legal move validation, move history, analysis depth controls, best-move display, and evaluation bar.
• AI Coach — local coach pipeline that explains Stockfish analysis in beginner-friendly language.
• Progress — estimated Elo, puzzle/lesson counts, streaks, rating history, and weakness tracking.
• On-device model support — model metadata plus runtime/local GGUF download support; large model blobs are intentionally not stored in Git.

See USER_MANUAL.md for end-user usage and iPhone installation instructions.

Project Structure

ChessCoachApp/          SwiftUI iOS application
ChessCoachShared/       Board model, pieces, moves, FEN, themes, persistence helpers
ChessCoachEngine/       ChessEngine protocol, Stockfish adapter, Lc0 adapter hook, LLM service
ChessCoachCoach/        Lessons, puzzles, opening book, coach engine, progress tracker
*Tests/                 Unit test targets for app, shared, engine, and coach layers
project.yml             XcodeGen project definition
SPEC.md                 Product/technical specification
TEST_PLAN.md            Test plan
USER_MANUAL.md          User-facing manual

Requirements

• macOS with Xcode
• iOS 17.0+ target device/simulator
• XcodeGen
• Swift 5.9 / Xcode 16 project settings

Install XcodeGen if needed:

brew install xcodegen

Build

Generate the Xcode project:

xcodegen generate

Open in Xcode:

open ChessCoach.xcodeproj

Or build from the terminal:

xcodebuild \
  -project ChessCoach.xcodeproj \
  -scheme ChessCoachApp \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  clean build

If your simulator name differs, list destinations:

xcodebuild -project ChessCoach.xcodeproj -scheme ChessCoachApp -showdestinations

Test

Run the full test suite:

xcodebuild \
  -project ChessCoach.xcodeproj \
  -scheme ChessCoachApp \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  test

Build from Source

# 1. Fetch build dependencies (Stockfish WASM + LLM model, ~1 GB total)
./scripts/bootstrap.sh

# 2. Generate the Xcode project
xcodegen generate

# 3. Build
xcodebuild -project ChessCoach.xcodeproj \
  -scheme ChessCoachApp \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  build

CI / automated builds: use ./scripts/bootstrap.sh --fetch to download all assets without prompts.

Install on iPhone

1. Run ./scripts/bootstrap.sh to download build dependencies.
2. Run xcodegen generate.
3. Open ChessCoach.xcodeproj.
4. Select the ChessCoachApp scheme.
5. Select your connected iPhone as the destination.
6. Configure signing under Signing & Capabilities.
7. Press Cmd+R.

More detailed steps are in USER_MANUAL.md.

Local Engine and Model Notes

• Stockfish is the default analysis engine. The WASM build is downloaded automatically by scripts/bootstrap.sh.
• Lc0Adapter is present as an alternate/future adapter hook.
• GGUF model binaries are not committed — scripts/bootstrap.sh downloads them before the build.
• Model metadata lives in ChessCoachShared/LocalInferenceConfig.swift.

Current default model metadata:

Field	Value
Display name	DeepSeek-R1 Distill (1.5B)
Hugging Face repo	unsloth/DeepSeek-R1-Distill-Qwen-1.5B-GGUF
File name	DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf
Size	~1065 MB

The chess engine evaluates positions. The LLM coach explains engine output; it is not the source of chess evaluation truth.

License

MIT. See LICENSE.