ChessAI – Xadrez contra Claude
devasur/chessai
Jogue xadrez contra Claude em um tabuleiro interativo com IA comentando cada lance
Ver no GitHubSkill que permite jogar xadrez contra um agente Claude em tempo real. O jogador controla as peças brancas em um tabuleiro interativo do navegador, enquanto Claude (subagente) controla as pretas, comentando cada movimento. Sem necessidade de API key — usa a infraestrutura de subagents da sua assinatura Claude Code.
Instalação
npx convez-ai devasur/chessai1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aprender estratégia xadrez com feedback de IA
- Demonstração lúdica de capacidades de raciocínio de Claude
- Entretenimento educativo integrado ao workflow de coding
Veredito

Projeto bem executado que exemplifica economia de tokens: move a lógica determinística (regras, board state, UI) para Node/JS puro e reserva Claude apenas para decisão de lance. Engenhoso e funcional — mais hobby educativo que ferramenta produtiva, mas code-sound e sem frivolidades.
README
A tradução para o português deste README ainda está na fila.
♛ chessai
Play chess against Claude Code.
You move white on a tactile browser board. A background Claude agent plays black — replying to every move with a comment and its reasoning.
▶ Watch the 60-second demo — install, launch, and a full game
Install in two lines — inside Claude Code:
/plugin marketplace add devasur/chessai
/plugin install chessai@chessai
…then run /chessai:chess and make your move.
♟ ♞ ♝ ♜ ♛ ♚
Why this exists
Most "LLM plays a game" projects are one giant prompt that bloats with every move and bills you per turn. chessai goes the other way: the only thing that needs a model is choosing a move. Everything else — rules, legality, board state, the UI — is plain, deterministic Node and browser JS.
The opponent is a Claude subagent, so on a Claude Code subscription your inference is already covered: no API key, no metered per-move billing. And because nothing about the game is Claude-specific, the brain is ~one function you can swap for any harness (see Fork it).
Quick start
Requires Node.js on your
PATH. The plugin only bundles files — no build step, no other runtime.
1 · Add the marketplace and install (inside Claude Code):
/plugin marketplace add devasur/chessai
/plugin install chessai@chessai
This registers the skill /chessai:chess and the agent chessai:chess-ai.
2 · Play:
/chessai:chess
The skill starts the Node server, opens the board in a chromeless app-style window (Chromium-family browsers; falls back to your default), and spawns the AI opponent. Click a piece, then its destination — black replies within a couple of seconds, with commentary in the move-list panel.
- New board → another game in its own window for side-by-side play.
- Games → list every board; switch, pop out, or delete.
- Skin swatches → switch theme (saved per game).
- Window geometry:
CHESSAI_WIN_SIZE="W,H",CHESSAI_WIN_POS="X,Y".
From a clone of this repo, launch just the server + UI (you'll be playing both sides, or wire up your own driver):
node skills/chess/tools/server.cjs --port 4577 --open
For local plugin development, skip the marketplace entirely:
claude --plugin-dir /path/to/chessai
The board
A dark "Midnight Study" theme (plus Ivory and Emerald skins) — inlaid board, brass accents, grain + vignette, and a full legal-move engine in the browser. You can only make legal moves, with reachable squares highlighted: dots for quiet moves, rings for captures. Castling, en passant, promotion, check, checkmate and stalemate are all handled, and the client declares the result.
The engine is validated with perft against standard positions — startpos, Kiwipete, en-passant and promotion positions all match known node counts — so move generation, including pins and through-check castling, is provably correct.
How it works
Three clean layers, one rule: the only thing that needs an LLM is choosing a move.
you (white) node server.cjs chess-ai agent
browser board ◀─HTTP─▶ multi-game state + FEN ◀─HTTP─▶ (Claude subagent, Bash-only:
(legal-move engine) REST + web UI; no brain poll /pending?all=1 → pick
moves → POST; batched,
backs off, self-stops)
| Layer | File | Role |
|---|---|---|
| Plugin | .claude-plugin/plugin.json | Packaging only. Bundles the skill, tools, and agent so Claude Code discovers them on install. No game logic. |
| Server | skills/chess/tools/server.cjs | Authoritative state for every game (FEN, castling, en passant, promotion, persistence) + REST API + web UI. No chess intelligence — pure plumbing. |
| Browser | skills/chess/tools/web/*, board.html | The clickable UI and the human's legal-move engine; detects and posts the result. |
| Agent | agents/chess-ai.md | The brain. Restricted to Bash, holds no game state. Polls for boards needing black, picks moves, POSTs them. |
The web layer is modular ES modules: engine.js (pure rules), api.js (REST client), view.js (DOM), app.js (controller), theme.css + board.css.
Light on your plan
The AI opponent is the only part that spends tokens — and it's built to stay light. It carries only the Bash tool and keeps no game history, so each move is a small, roughly fixed cost (~5–6k tokens of context) instead of a transcript that grows all game.
| Activity | Token cost |
|---|---|
| Engine start | ~5–6k tokens once, when the agent first loads — then cached |
| Per move, one board | a few thousand new tokens; most context is cached and re-read cheaply |
| Per move, many boards | shared — one wake plays every pending board at once |
| Idle / walked away | ≈ nothing (polling is plain curl), then it stops itself after ~24 min |
The model only runs when there's actually a move to make — waiting for your move is a token-free curl long-poll — so a game left sitting costs almost nothing, and a forgotten one shuts itself off rather than draining tokens in the background.
Numbers are from recent games on Sonnet; actual cost scales with the model set in agents/chess-ai.md frontmatter.
Fork it to any harness
Nothing about the game is Claude-specific — the server and browser are plain Node/JS with zero Claude dependency. The brain is ~one function against a three-call contract:
1. GET /api/pending?all=1&wait=1 → [{ id, fen, move_count }, …] blocks until boards need black
2. choose a move per board from its FEN
3. POST /api/games/<id>/move { from, to, san, by:"ai", expected_ply:move_count, … }
To fork to any harness — a Python script, a cron job, a different model, the Anthropic API directly — replace agents/chess-ai.md with your own loop implementing those three calls. Nothing else changes:
&wait=1long-polls, so your loop blocks on one call instead of busy-waiting.?all=1returns every pending board, andexpected_plyis a compare-and-swap guard — so your driver can be stateless and never track games itself.- One server backs every session;
/api/healthreportschessai_agent_active, so a second launcher reuses the running server instead of starting a duplicate.
| Method | Path | Notes |
|---|---|---|
GET | / | clickable web board |
GET | /api/health | { ok, service:"chessai", version, games, chessai_agent_active } |
GET | /api/games | list every game (id, name, fen, turn, status, theme, opponent, last move…) |
POST | /api/games | create a game (server assigns the three-word id) |
GET | /api/pending?all=1 | array of every board needing black — the agent's source |
GET | /api/pending?all=1&wait=1 | same, but long-polls: holds open until a board needs black (coalescing near-simultaneous moves into one batch), or ~8 min → [] |
GET | /api/games/<id> | full state incl. history |
POST | /api/games/<id>/move | { from, to, san?, promotion?, by?, expected_ply?, harness?, model?, comment?, reasoning? } |
POST | /api/games/<id>/reset | reset to the starting position |
POST | /api/games/<id>/status | { status } — end the game |
POST | /api/games/<id>/theme | { theme } — midnight | marble | emerald |
POST | /api/games/<id>/opponent | { harness?, model?, name? } — who plays black |
DELETE | /api/games/<id> | delete the game and its saved file |
CLI wrapper (from a clone): node skills/chess/tools/chess-api.cjs games 4577
- Stop the whole session — in Claude Code, stop the server background task and the
chess-aiagent task (both started withrun_in_background). Close the board window normally. - Pause only the AI — stop just the
chess-aiagent task; the server and boards stay up. Relaunch the agent to resume. - The agent stops itself after ~24 min idle. To resume, make a move and ask Claude to relaunch the opponent.
- Free the port — if
server.cjssays the port is in use, the previous server is still running; stop that task (orpkill -f server.cjs).
Games survive all of this: they persist to ~/.chessai/games/<id>.json (override with CHESSAI_DATA_DIR) and reload when the server restarts.
- Where the rules live: the server board model is intentionally permissive (applies any well-formed move) — keeping it dumb. Legality is enforced by the browser engine for the human, while the agent chooses its own legal moves for black. The client detects and posts the result (checkmate, stalemate, fifty-move).
- Statelessness by design: the
expected_plycompare-and-swap guard lets the agent (or any forked driver) submit a move without tracking games — the server rejects a move computed against a stale position, so one driver can serve every parallel board safely. - Upgrades:
/plugin update chessaipulls the latest skill and agent. Theversionin.claude-plugin/plugin.jsondrives update detection (bump per release); refresh the catalog first with/plugin marketplace update chessai.
Requirements
- Node.js on your
PATH(the server and tools are Node — no npm install, no build step). - Claude Code to install the plugin and host the AI opponent. (For the board alone, Node is enough.)
- A Chromium-family browser for the chromeless app window — otherwise it opens in your default browser.
License
MIT © devasur
♚