An AI-powered chess tutor application built with Next.js, featuring interactive chess gameplay, AI coaching, and real-time analysis.
Chester is an advanced AI-powered chess tutor designed to take your chess skills to the next level. With personalized guidance, interactive lessons, and intelligent analysis, Chester empowers you to enhance your strategic thinking, sharpen your tactics, and elevate your overall performance on the chessboard.
- Interactive Chess Board: Play chess with drag-and-drop interface using
react-chessboard - AI-Powered Coaching: Get personalized chess advice based on your skill level (Novice to Expert)
- Real-time Analysis: Stockfish engine integration for position evaluation and best move suggestions
- Command Palette: Quick access to chess commands via ⌘K keyboard shortcut
- Skill-Based Adaptation: Different coaching styles and analysis depth based on user's ELO rating
Chester uses a centralized command registry system for extensibility and type safety:
- /next-move (
/nm): Get the engine's best move with coaching explanation - /breakdown (
/bd): Analyze threats, motifs, and plans without move recommendations - /mind-reader (
/mr): Explain likely plans for both sides from the principal variation - /opponent (
/opp): Show opponent's best reply and main line - /coach (
/c): General tutoring with command suggestions
Commands support aliases for faster input and are organized by category (Analysis, Training, Game).
- Next.js 16 with App Router
- TypeScript for type safety
- Tailwind CSS with dark mode support via
next-themes - Radix UI components for accessible UI
- Zustand for state management with persistence
- AI SDK integration with OpenAI GPT-4o-mini
- Stockfish 15 chess engine for position analysis
- Biome for formatting, linting, and import sorting
chester/
├── app/ # Next.js app router pages and API routes
│ ├── api/ # API endpoints for chat and chess analysis
│ ├── layout.tsx # Root layout with theme provider
│ └── page.tsx # Main application page
├── components/ # React components
│ ├── ai-elements/ # AI chat and UI components
│ ├── ui/ # Radix UI based components
│ ├── chat.tsx # Main chat interface
│ ├── chessboard.tsx # Interactive chess board
│ └── chester-command-dialog.tsx # Command palette
├── lib/ # Utility functions and server-side logic
│ ├── commands/ # Command registry system
│ │ ├── registry.ts # Central command definitions
│ │ ├── service.ts # Command resolution and validation
│ │ └── types.ts # Command type definitions
│ └── server/ # Stockfish engine integration
├── store/ # Zustand state management
├── config/ # Site configuration
├── types/ # TypeScript type definitions
└── public/ # Static assets
- Uses OpenAI's GPT-4o-mini via AI SDK for natural language coaching
- Stockfish engine provides chess analysis and move evaluation
- Skill-based prompting with different depth and multiPV settings per ELO bracket
- Real-time streaming responses with chain-of-thought reasoning
- Registry Pattern: Centralized command definitions with metadata (title, description, aliases, colors)
- Type Safety: TypeScript integration prevents invalid command usage
- Extensibility: Easy to add new commands without touching multiple files
- Validation: Runtime command validation with suggestions for typos
- Categories: Commands organized by purpose (Analysis, Training, Game)
- Zustand store with localStorage persistence for game state
- Tracks board position, ELO rating, valid moves, and AI play state
- DevTools integration for development debugging
chess.jsfor game logic and move validationreact-chessboardfor interactive board UI- Stockfish WebAssembly for position analysis
- Adaptive analysis depth based on user skill level
- Responsive design with Tailwind CSS
- Dark/light theme support
- Command palette for quick command access
- Real-time chat interface with message streaming
- Visual feedback for selected squares and valid moves
- Bun 1.3+
- OpenAI API key (for AI coaching functionality)
- Clone the repository:
git clone https://github.com/conceptcodes/chester.git
cd chester- Install dependencies:
bun install
3. Set up environment variables:
```bash
cp .env.example .env.local
# Add your OpenAI API key to .env.local
OPENAI_API_KEY=your_api_key_here- Run the development server:
bun dev
# or
npm run dev- Open http://localhost:3000 in your browser.
- Set Your Skill Level: Use the dropdown to select your ELO rating (Novice, Intermediate, Advanced, Expert)
- Play Chess: Make moves by dragging pieces or clicking squares
- Get Coaching: Use commands like
/next-moveor/breakdownto get AI analysis - Use Command Palette: Press ⌘K to quickly access all available commands
- Learn: Read the chain-of-thought reasoning to understand the AI's analysis process
bun dev/npm run dev- Start development serverbun build/npm run build- Build for productionbun start/npm run start- Start production serverbun lint/npm run lint- Run Biome linterbun typecheck/npm run typecheck- Run TypeScript type checking
- Biome for formatting and linting
- TypeScript strict mode enabled
- ESLint configuration for code quality
- Prettier for consistent code formatting
- Different system prompts per command type (coach, breakdown, mind-reader, etc.)
- Skill-level specific guidance in prompts
- Perspective-based responses (White vs Black)
- Stockfish analysis integrated into AI context
- Dynamic imports for chessboard component
- ResizeObserver for responsive board sizing
- Streaming responses for real-time feedback
- WebAssembly Stockfish for efficient chess analysis
- Game state persists across page reloads
- ELO rating and board position saved to localStorage
- Zustand middleware for automatic persistence
Licensed under the MIT license.