Game Sync
Import and sync games from Lichess.org and Chess.com into a single local database.
Your chess database, analysis engine, and AI coach in one assistant.
ChessClaw watches your games on Lichess.org and Chess.com, brings them into a single database, analyzes tactical misses, renders training puzzles, and answers natural-language questions about your chess games.
What It Does
Built for real chess work, not generic assistant fluff.
ChessClaw is focused on one job: helping you understand, organize, and improve your chess through a secure personal assistant that works from your own data.
Natural-Language Insights
Ask questions about openings, opponents, results, trends, recent games, or tactical mistakes.
Missed-Mate Analysis
Run Stockfish-backed analysis to find missed mating opportunities and review them later.
Puzzle Rendering
Turn missed tactics into visual puzzle images you can review on demand or on a schedule.
Scheduled Chess Tasks
Set recurring jobs for syncs, insights, reminders, and training flows that message you back.
Training From Your Own Games
Turn your own missed opportunities into repeatable study material instead of generic puzzle feeds.
Architecture
Small enough to understand. Focused enough to trust.
ChessClaw is intentionally lean: one Node.js process, one assistant workspace, one configured chat, one persistent chess database, and isolated agent runs.
Telegram Bot
→
SQLite State
→
Single Queue
→
Containerized Codex Agent
→
Chess Actions + Reply
The host handles Telegram, task scheduling, database access, and trusted chess scripts. The assistant runs in an isolated container and uses MCP tools to query the chess database, sync games, analyze positions, and render puzzle images.
Philosophy
Forkable, inspectable, and customized by code instead of config sprawl.
Small Enough to Understand
One process, a small codebase, and a clear data flow you can actually audit.
Secure by Isolation
Agent sessions run in containers and only see explicitly mounted directories.
Built for One User
Not a generic framework. It is working software shaped around a real chess workflow.
AI-Native
No wizard-heavy setup. Codex guides installation, customization, and debugging.
Skills Over Bloat
New capabilities should arrive as transformation skills, not permanent complexity in core.
Chess-First
The assistant exists to help you improve at chess, not to become a general-purpose chatbot.
Quick Start
Clone it, open codex, and run the setup skill.
$>git clone https://github.com/fmbenhassine/chessclaw.git
$>cd chessclaw
$>codexExample Requests
Talk to ChessClaw the way you already think about your chess.
