# ♞ 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

```bash
# 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](https://github.com/stefan-kp/chess_tutor) — licensed under GPL-3.0.