Files

T

Build and publish Docker image to GHCR / build-and-push (push) Has been cancelled

Details

feat: merge chess_tutor + OpenRouter abstraction

- Merged stefan-kp/chess_tutor into chess-project with full feature set
- Preserved Hermes agent files (agents/, .gitea/, AGENTS.md)
- Added OpenRouter abstraction layer (src/lib/openrouter.ts)
- Created ModelSelector dropdown component with 9 models
- Updated API routes (chat + opening explanation) to use OpenRouter
- Updated useTutorChat to route through OpenRouter API
- Updated onboarding and API key input for OpenRouter
- Created tasks.md with sprint 1 plan
- Updated README with new architecture details

2026-06-20 19:47:16 +00:00

2.9 KiB

Raw Blame History

♞ Chess Tutor

AI-powered chess tutor with Stockfish analysis. Play against customizable AI coach personalities. Supports multiple AI models via OpenRouter.

Features

Play chess against Stockfish with an AI coach giving you real-time feedback
AI personalities — choose from Hype Streamer, Professional Coach, Russian Grandmaster, and more
Model selector — switch between Gemini, Claude, GPT, Grok, DeepSeek, and Llama
Opening trainer — practice specific openings with move validation
Tactical puzzles — test your pattern recognition
Game analysis — get AI feedback on your games
Multi-language — English, German, French, Italian, Polish

Quick Start

# Install
npm install

# Run
npm run dev

Open http://localhost:3050 — the onboarding page will walk you through setup.

Tech Stack

Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS 4
Chess: chess.js, react-chessboard
Engine: Stockfish (in-browser via stockfish.js WASM)
AI: OpenRouter API (multi-provider: Gemini, Claude, GPT, Grok, DeepSeek, Llama)
Mobile: Capacitor (iOS/Android)

Environment

Copy .env.example to .env.local:

OPENROUTER_API_KEY=sk-or-...
NEXT_PUBLIC_DEFAULT_MODEL=google/gemini-2.5-flash

Or enter your API key through the UI on first launch.

Hermes Agent Integration

This repo includes Hermes agent role files for multi-agent development:

File	Purpose
`AGENTS.md`	High-level project guidance for Hermes agents
`tasks.md`	Sprint tasks with Now / Next / Backlog
`agents/HA_*.md`	Role-specific instructions (Architect, Coder, DevOps, etc.)
`.gitea/`	Issue and PR templates
`docs/WORKFLOW.md`	Collaboration workflow

Available AI Models

Model	Provider
Gemini 2.5 Flash	Google
Gemini 2.5 Pro	Google
Claude Sonnet 4	Anthropic
Claude 3.5 Haiku	Anthropic
GPT-4o	OpenAI
GPT-4o Mini	OpenAI
DeepSeek Chat	DeepSeek
Grok 3	xAI
Llama 3.1 70B	Meta

Project Structure

src/
├── app/                    # Next.js pages and API routes
│   ├── api/v1/llm/         # OpenRouter-backed AI endpoints
│   ├── learning/           # Opening trainer and tactics
│   ├── onboarding/         # First-run setup flow
│   └── settings/           # Game settings
├── components/             # React components
│   ├── ChessGame.tsx       # Main game component
│   ├── Tutor.tsx           # AI tutor chat panel
│   ├── ModelSelector.tsx   # Model dropdown (OpenRouter)
│   └── ...
└── lib/
    ├── openrouter.ts       # OpenRouter abstraction layer
    ├── server/tutorPrompt.ts # Prompt templates
    └── engine/              # Stockfish integration

Credits

Based on stefan-kp/chess_tutor — licensed under GPL-3.0.

2.9 KiB Raw Blame History