convez.ai
SkillUtilidadesIntermediário
devasur

ChessAI – Xadrez contra Claude

devasur/chessai

Jogue xadrez contra Claude em um tabuleiro interativo com IA comentando cada lance

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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/chessai

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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.

License: MIT Claude Code plugin version runtime: Node.js engine: perft-verified no API key

▶  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)
LayerFileRole
Plugin.claude-plugin/plugin.jsonPackaging only. Bundles the skill, tools, and agent so Claude Code discovers them on install. No game logic.
Serverskills/chess/tools/server.cjsAuthoritative state for every game (FEN, castling, en passant, promotion, persistence) + REST API + web UI. No chess intelligence — pure plumbing.
Browserskills/chess/tools/web/*, board.htmlThe clickable UI and the human's legal-move engine; detects and posts the result.
Agentagents/chess-ai.mdThe 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.

ActivityToken cost
Engine start~5–6k tokens once, when the agent first loads — then cached
Per move, one boarda few thousand new tokens; most context is cached and re-read cheaply
Per move, many boardsshared — 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=1 long-polls, so your loop blocks on one call instead of busy-waiting.
  • ?all=1 returns every pending board, and expected_ply is a compare-and-swap guard — so your driver can be stateless and never track games itself.
  • One server backs every session; /api/health reports chessai_agent_active, so a second launcher reuses the running server instead of starting a duplicate.
MethodPathNotes
GET/clickable web board
GET/api/health{ ok, service:"chessai", version, games, chessai_agent_active }
GET/api/gameslist every game (id, name, fen, turn, status, theme, opponent, last move…)
POST/api/gamescreate a game (server assigns the three-word id)
GET/api/pending?all=1array of every board needing black — the agent's source
GET/api/pending?all=1&wait=1same, 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>/resetreset 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-ai agent task (both started with run_in_background). Close the board window normally.
  • Pause only the AI — stop just the chess-ai agent 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.cjs says the port is in use, the previous server is still running; stop that task (or pkill -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_ply compare-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 chessai pulls the latest skill and agent. The version in .claude-plugin/plugin.json drives 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

♚

Ver o original no GitHub

Bom para

Relacionados