♟️ Chess Analyzer

A professional cross-platform desktop application for analyzing chess games from Chess.com with multi-provider AI-powered insights and comprehensive game analysis.

Chess Analyzer provides chess players with detailed move-by-move analysis, blunder detection, and personalized improvement suggestions powered by xAI Grok. Features both modern GUI and command-line interfaces with local database storage.

✨ Key Features

🎯 Advanced Chess Analysis

• Move-by-Move Evaluation: Detailed analysis with centipawn loss detection and blunder identification
• Game Phase Classification: Intelligent opening, middlegame, and endgame analysis
• Accuracy Calculation: Overall game accuracy percentage with detailed statistics
• Position Evaluation: Static analysis with best move suggestions using Stockfish engine
• Batch Processing: Analyze multiple games simultaneously with progress tracking

🤖 AI-Powered Insights (Multi-Provider Support)

• Multiple AI Providers: Choose from xAI Grok, OpenAI GPT-4, or Anthropic Claude
• Automatic Fallback: System automatically selects the first available AI provider
• Personalized Advice: Context-aware chess improvement recommendations
• Strategic Guidance: Opening, middlegame, and endgame strategy suggestions
• Mistake Analysis: Detailed explanations of errors with improvement tips
• Natural Language: Human-readable analysis and advice

💾 Smart Data Management

• Chess.com Integration: Fetch games without authentication (public API)
• Local SQLite Database: Efficient caching with fast querying capabilities
• Date Range Filtering: Focus analysis on specific time periods
• Game Export: Save analysis results in multiple formats

🖥️ Professional User Interface

• Modern GUI: Polished Tkinter-based desktop application with intuitive design
• Real-time Progress: Live progress bars and status updates during analysis
• Color-Coded Output: Visual distinction for different types of information
• Settings Management: Easy credential management and configuration
• Command-Line Tools: Full CLI support for automation and scripting

🔐 Security & Privacy

• Local Processing: All analysis happens on your device
• Optional Authentication: Use Chess.com credentials for enhanced features
• Secure Storage: Local credential storage with Git exclusion
• No Data Transmission: Your games and analysis stay private
• API Key Protection: Never commit API keys to version control

⚠️ IMPORTANT: Never commit your config.local.ini file containing API keys to version control. It is automatically excluded by .gitignore for your security.

📦 Distribution Ready

• Standalone Executables: PyInstaller-packaged apps for Windows, macOS, and Linux
• No Installation Required: Works without Python installation on target machines
• Cross-Platform: Consistent experience across all major operating systems
• Professional Packaging: Proper app bundles with icons and metadata

🚀 Quick Start

🔒 Security First

Before you begin: This application uses AI services that require API keys. Your API keys are stored locally and never transmitted except to the AI providers. However, for your security:

• ✅ config.local.ini is automatically excluded from Git commits
• ✅ API keys are only used for AI analysis requests
• ✅ No sensitive data is logged or stored
• ❌ Never share your config.local.ini file
• ❌ Never commit API keys to version control

🌐 Option 1: Web Interface (Recommended)

# Clone the repository
git clone https://github.com/dentity007/chess-analyzer.git
cd chess-analyzer

# Set up virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Launch the web interface
python start_web.py
# OR use the shell script
./start_web.sh

Web Interface Features:

• Modern responsive web interface with Bootstrap styling
• Real-time progress updates with AJAX
• Cross-platform compatibility (works on any device with a browser)
• No installation required on target machines
• Runs on localhost for security and privacy

🎯 Option 2: macOS Application Bundle

# Download ChessAnalyzer-Installer.dmg from GitHub Releases
# Double-click the DMG file to mount it
# Drag ChessAnalyzer.app to your Applications folder
# Eject the DMG and launch ChessAnalyzer from Applications

# Alternative: Direct app bundle download
# Download ChessAnalyzer.app from GitHub Releases
# Double-click ChessAnalyzer.app to launch the GUI
# Or use command line from within the app bundle:
ChessAnalyzer.app/Contents/MacOS/ChessAnalyzer --help

💻 Option 3: Standalone Executable

# Download the latest release for your platform from GitHub
# Launch the GUI (double-click or run):
./ChessAnalyzer --gui

# Use CLI commands:
./ChessAnalyzer fetch yourusername
./ChessAnalyzer analyze --username yourusername
./ChessAnalyzer auth-test

🔧 Option 4: From Source (Development)

# Clone the repository
git clone https://github.com/dentity007/chess-analyzer.git
cd chess-analyzer

# Set up virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Launch GUI
python3 -m src.main --gui

# Or use CLI commands
python3 -m src.main fetch yourusername
python3 -m src.main analyze --username yourusername

📦 Prerequisites

• Python 3.8+ (for source installation)
• macOS 10.12+ (for macOS builds)
• Windows 10+ (for Windows builds)
• Linux (Ubuntu 18.04+, CentOS 7+, etc.)

🎮 Usage Guide

GUI Mode (Recommended for beginners)

# Launch the graphical interface
python3 -m src.main --gui
# OR double-click ChessAnalyzer.app on macOS

GUI Features:

• Enter your Chess.com username
• Set up credentials (optional, for enhanced features)
• Fetch and analyze your games
• View detailed analysis with AI insights
• Save analysis results

Command Line Mode (Advanced users)

# Show all available commands
python3 -m src.main --help

# Fetch games for a user
python3 -m src.main fetch yourusername

# Analyze games with AI insights
python3 -m src.main analyze --username yourusername

# Test authentication setup
python3 -m src.main auth-test

# Show player statistics
python3 -m src.main stats yourusername

⚙️ Configuration

🔒 SECURITY WARNING: Never commit your config.local.ini file to version control. It contains sensitive API keys and will be automatically ignored by Git.

Create config.local.ini in the project root:

[chess_com]
username = your_chess_username
password = your_password  # Optional, for premium features

[ai]
api_key = your_xai_api_key  # Optional, enables AI-powered analysis

AI Configuration:

• xAI Grok: Get your API key from x.ai/api
• OpenAI GPT: Get your API key from platform.openai.com/api-keys
• Anthropic Claude: Get your API key from console.anthropic.com
• Add the appropriate key to the [ai] section for enhanced chess analysis
• The system automatically uses the first available AI provider
• Without API keys, basic analysis is still available

Supported AI Providers:

• xAI Grok: Specialized chess analysis with natural language explanations
• OpenAI GPT-4: Advanced strategic analysis and improvement suggestions
• Anthropic Claude: Balanced analysis with detailed position evaluation

Configuration Example:

[ai]
xai_api_key = your_xai_key_here
openai_api_key = your_openai_key_here
anthropic_api_key = your_anthropic_key_here

🔍 Verify Your Configuration is Secure

After setting up your API keys, verify they won't be committed:

# Check that config.local.ini is ignored by Git
git status --ignored | grep config.local.ini

# Verify the file is in .gitignore
grep "config.local.ini" .gitignore

# Test that your API key is loaded (without exposing it)
python3 -c "from src.ai.grok_client import GrokClient; client = GrokClient(); print('API key loaded:', client.is_available())"

Note: The config file is automatically excluded from Git for security.

Sample Output

Analyzing games for hikaru

📊 Game Analysis Summary
═══════════════════════════════════════════════════════════════
Games Analyzed: 5
Total Moves: 1,247
Average Accuracy: 89.2%
Blunders Found: 3
Mistakes Found: 12

🎯 Top Blunders:
• Move 23 in Game #3: Qd8-h4 (lost 420 cp)
• Move 15 in Game #1: Nf3-g5 (lost 380 cp)
• Move 31 in Game #4: Bc1-f4 (lost 350 cp)

🤖 AI Analysis:
Your recent games show strong tactical awareness with an average accuracy of 89.2%.
The most common issues were in the opening phase where piece development could be more efficient.
Consider focusing on king safety in the middlegame - this appeared in 3 of the 5 games analyzed.

⚙️ Configuration

🏗️ Architecture & Design

5-Layer Architecture

Chess Analyzer follows a modular 5-layer architecture for maintainability and scalability:

1. Data Fetching Layer (src/api/)

• Chess.com Public API integration
• Rate limiting and error handling
• Local credential storage and management
• Support for both authenticated and anonymous access

2. Storage Layer (src/db/)

• SQLite database for efficient game caching
• Optimized queries for game retrieval and analysis
• Automatic schema management and migrations
• Thread-safe database operations

3. Analysis Layer (src/analysis/)

• Stockfish chess engine integration
• Move-by-move position evaluation
• Blunder detection algorithms
• Game phase classification (opening/middlegame/endgame)

4. AI Guidance Layer (src/ai/)

• xAI Grok API integration
• Natural language chess advice generation
• Context-aware improvement suggestions
• Personalized learning recommendations

5. UI Layer (src/gui.py, src/main.py, src/web_app.py)

• Modern Tkinter-based GUI application
• Command-line interface with Click framework
• Flask-based web application with responsive HTML interface
• Progress tracking and user feedback
• Cross-platform compatibility (desktop and web)

Key Design Patterns

• Observer Pattern: Real-time progress updates
• Factory Pattern: Dynamic component instantiation
• Strategy Pattern: Pluggable analysis engines
• Repository Pattern: Data access abstraction

📊 Current Status (v0.1.0)

✅ Completed Features

• ✅ Web Interface: Modern Flask-based web application with responsive design
• ✅ macOS Application Bundle: ChessAnalyzer.app (35MB) - fully functional standalone executable
• ✅ Cross-Platform CLI: Complete command-line interface with all core features
• ✅ Chess.com API Integration: Public API access with rate limiting and error handling
• ✅ Local Database: SQLite storage with efficient game caching and querying
• ✅ Stockfish Integration: Chess engine for move evaluation and blunder detection
• ✅ xAI Grok Integration: AI-powered chess improvement suggestions
• ✅ Build System: Automated macOS executable creation with build_macos.sh
• ✅ Security: Local credential storage in config.local.ini (gitignored)
• ✅ GUI Application: Modern Tkinter interface with credential management
• ✅ Error Handling: Comprehensive error handling and graceful degradation

🚧 Development Pipeline

• Windows Executable: Build system preparation
• Linux Executable: Build system preparation
• Enhanced GUI: Additional features and improvements
• Performance Optimizations: Analysis speed and memory usage
• Extended Testing: Comprehensive test coverage expansion

🧪 Quality Metrics

• Test Coverage: Core functionality tested
• Build Status: ✅ macOS builds successful
• Code Quality: Comprehensive error handling and logging
• Documentation: Complete API documentation and user guides

🧪 Testing

Run the comprehensive test suite:

# All tests
pytest tests/

# With coverage report
pytest tests/ --cov=src --cov-report=html

# Specific test file
pytest tests/test_api_client.py -v

# Run tests in parallel
pytest tests/ -n auto

Current Status: ✅ All tests passing locally (48 tests)

Test Categories

• API Tests: Chess.com integration and rate limiting
• Database Tests: SQLite operations and data integrity
• Analysis Tests: Chess engine and move evaluation
• AI Tests: Grok API client and prompt generation
• CLI Tests: Command-line interface validation
• GUI Tests: Tkinter interface functionality

📦 Building from Source

Prerequisites

• Python 3.8 or higher
• pip package manager
• Git (for cloning)

macOS Build (Recommended)

# Make build script executable
chmod +x build_macos.sh

# Run the macOS build script
./build_macos.sh

# Output: dist/ChessAnalyzer.app (35MB macOS application bundle)

Cross-Platform Build

# Install build dependencies
pip install pyinstaller

# Build standalone executable
python build.py

# Or build manually
pyinstaller ChessAnalyzer.spec

Simple Build

# For quick testing builds
./build_simple.sh

Output

• dist/ChessAnalyzer.app - macOS application bundle (35MB)
• dist/ChessAnalyzer - Main executable (cross-platform)
• dist/ChessAnalyzer.exe - Windows executable

🐛 Troubleshooting

Common Issues

403 Forbidden from Chess.com API

• Some users have private profiles
• Try with a different username or public profile

Stockfish Not Found

# Download and place in project directory
curl -o stockfish https://example.com/stockfish-binary
chmod +x stockfish

AI Features Not Working

# Check API key
echo $XAI_API_KEY

# Verify key format
python -c "import os; print('Key set:', bool(os.getenv('XAI_API_KEY')))"

Database Issues

# Reset database
rm -f games.db analysis_cache.db
python -m src.main fetch yourusername

Getting Help

1. Check the 📚 Wiki for detailed guides
2. Review existing issues for similar problems
3. Open a new issue with detailed information

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# Fork and clone
git clone https://github.com/yourusername/chess-analyzer.git
cd chess-analyzer

# Set up development environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

# Run tests
pytest tests/

# Start developing!

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Update documentation if needed
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

📊 Performance

• Analysis Speed: ~2-5 seconds per game (depends on depth and hardware)
• Memory Usage: ~50MB base + ~10MB per concurrent analysis
• Storage: ~1KB per game in SQLite database
• Network: Efficient API usage with intelligent caching

🔄 Version History

See CHANGELOG.md for detailed version history.

Recent Releases

• v0.1.1 (Feb 2026): Security hardening (see below)
• v0.1.0: Production release with full feature set
• Pre-releases: Alpha and beta versions with core functionality

Security Hardening (v0.1.1, Feb 2026)

• Credential endpoint redacted: GET /api/load_credentials no longer returns the plaintext password. It returns has_password: true/false instead. The frontend prompts for re-entry when updating credentials.
• Debug mode disabled: Flask debug=True removed. The Werkzeug interactive debugger is no longer exposed.
• Error messages sanitized: All API error responses now return generic messages instead of raw exception strings (str(e)). Internal details are logged server-side only.
• Git history purged: config.local.ini was removed from all git history using git filter-repo. No credentials exist in any historical commit.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Chess.com for providing the public API
• python-chess library for chess board representation
• Stockfish engine for chess analysis
• xAI for Grok API access
• Open-source community for amazing tools and libraries

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Security Issues: security@chess-analyzer.dev
• 💬 General Discussion: GitHub Discussions

---

Made with ❤️ for chess enthusiasts worldwide