Chess CoachDocumentationThe Chess Coach handbook
The art ofa better move.
A worthy opponent. A thoughtful companion.
Play Stockfish on a local chessboard in Codex, then explore the position together in conversation. This is your guide to the first move—and everything that follows.
A board of your own
The board and engine run locally, with your game saved on your machine.
Understanding, move by move
Ask Codex about the very position on your board.
Return when you wish
One saved game. No clock. Room to think.
01Your first move
Set up your chess companion.
Install once. After that, ask Codex to open the board whenever you are ready to play.
Install the stable release
Install the complete stable package through the native GitHub marketplace.
Terminalcodex plugin marketplace add jovijovi/chess-coach --ref marketplace codex plugin add chess-coach@chess-coachThe existing preview uses ref marketplace-preview and plugin ID chess-coach@chess-coach-preview. The public repository requires no GitHub authentication.
Upgrade manually
Refresh the stable catalog and reinstall. For previews, use the chess-coach-preview catalog name.
Terminalcodex plugin marketplace upgrade chess-coach codex plugin add chess-coach@chess-coachStart a new Codex task after each upgrade. Older caches cannot overwrite a newer runtime.
Make your first move
Send the prompt in a new task. The plugin starts its local service and opens the board in the in-app browser.
Open the chessboard.
The default is White/Medium. The installed board and engine work offline; model conversation still uses the Codex service.
02At the board
A little room to think.
Choose your side and your challenge. Take a move back, turn the board around, or return to the game another day.
Move naturally
Drag a piece or select it and its destination. Legal squares are highlighted; keyboard moves and all four promotion choices are supported.
Keep your bearings
Follow the move list, last-move highlights, and check indicators. Flip the board whenever a different view helps.
Take a second look
Undo returns to before your last turn: your move and the engine reply, or just your move if the engine is still thinking.
Keep the story
Export PGN before a new game if you want to retain the score. A new game replaces the single save slot.
Find your pace
| Difficulty | Skill Level | Search per move |
|---|---|---|
| Easy | 0 | 200 ms |
| Medium · default | 5 | 500 ms |
| Hard | 10 | 1,000 ms |
Difficulty names are not calibrated ratings. When you play Black, Stockfish makes the opening move; undo preserves that first engine move.
The board supports English and Simplified Chinese. It follows the first supported browser language until you choose a language yourself. Your choice survives refreshes and service restarts, without changing the game or PGN.
03Beyond the move
Turn a position into understanding.
The board supplies engine hints. Your Codex conversation is where you explore the ideas behind them.
Understand the position
Analyze the current position. What should I be thinking about?
Look back at a decision
Explain my last move and compare it with the engine's alternatives.
Consider the next move
Give me a hint and explain the plan behind it.
Codex reads the current game and uses Stockfish analysis for that position. Analysis includes the half-move number (ply), FEN, game version, and legal variations. It does not change the board. Ask for explanations in either language.
04Under the surface
One board. A shared understanding.
The interactive board and Codex use the same game service. Expand a tool to see what it does and which inputs it expects.
show_boardOpen or resume the board
Returns the current game and a URL for the Codex in-app browser. The local service starts automatically when needed.
No inputs.
get_gameRead the complete game
Returns the position, complete history, legal moves, engine state, gameId, and revision.
No inputs.
new_gameStart a new game
Replaces the current save on an explicit request. Export PGN first if you want to keep the old score.
gameId, expectedRevision, playerColor (w | b), difficulty (easy | medium | hard).
make_movePlay your requested move
Validates the move, saves it, and schedules Stockfish’s reply. Squares use algebraic coordinates such as e2 and e4.
gameId, expectedRevision, from, to; optional promotion (q | r | b | n).
undo_turnReconsider the last turn
Cancels a pending search and restores the position before the previous human turn.
gameId, expectedRevision.
retry_engineRetry an engine reply
Retries after an engine timeout or exit, starting from the saved position. No replacement move is invented.
gameId, expectedRevision.
analyze_positionStudy a chosen position
Returns White-perspective scores and legal variations without changing the game. The result identifies its exact position and version.
gameId, expectedRevision; optional ply (0 is the starting position).
export_pgnTake your score with you
Returns the current PGN, a suggested filename, and local download information.
No inputs.
05A game worth keeping
Pick up where you left off.
Each move is saved before the engine replies. Closing the board leaves the current game ready for your next visit.
Your data stays local
| Path | Purpose |
|---|---|
~/.local/share/chess-coach/state.db | Current game and complete history |
~/.local/share/chess-coach/preferences.json | Language preference |
~/.local/share/chess-coach/runtime/ | Verified runtime files |
| activation-lock.db / service-lock.db | Separate SQLite process leases |
node ~/.local/share/chess-coach/runtime/control.js doctor
node ~/.local/share/chess-coach/runtime/control.js stopDoctor omits the access token. Stopping retains saves and language; reopen the board through Codex after a restart.
node ~/.local/share/chess-coach/runtime/control.js stop
codex plugin remove chess-coach@personal
cp -R ~/.local/share/chess-coach/runtime ~/.local/share/chess-coach/runtime-0.1-backupClose old tasks first. After installing the preview, run node <installed-plugin>/scripts/launch.mjs clean-runtime using the absolute path printed by Codex, then start a new task. Games, preferences, and other personal entries remain. Keep the backup until verified.
node ~/.local/share/chess-coach/runtime/control.js stop
node ~/.local/share/chess-coach/runtime/control.js clean-runtime
codex plugin remove chess-coach@chess-coach-previewClose chess tasks first. Clean-runtime is optional and removes only runtime files, preserving games and language. The stable identifier is chess-coach@chess-coach.
What if the engine stops responding?
Your move is saved. Use Retry; reopen the board after a disconnection and inspect service.log if necessary.
Will a failed update lose my game?
Updates stage and verify files before switching and health-checking the service. Failure restores previous runtime files without reverting the database. Crashes release locks; interrupted switches recover on the next launch.
How do I roll back intentionally?
Close tasks, stop the service, remove the plugin and runtime files, and remove only its catalog registration. Re-add a compatible immutable plugin-vVERSION ref; choose an existing RC ref from its Release to use the preview catalog. Keep the newer database. The 0.2.0 RCs retain the existing save format.
All platforms use the same data-directory convention. Direct CLI launches support CHESS_COACH_DATA_DIR; if Codex filters inherited variables, set it explicitly in the MCP environment and keep tasks and control commands consistent. A corrupt database produces an error instead of silently resetting.
06For the curious
Built to be understood.
React and TypeScript at the board. Node.js, chess.js, SQLite, and Stockfish behind it. A shared, versioned game state throughout.
The working toolkit
| Command | Purpose |
|---|---|
npm run dev | Build an isolated game in output/dev-data; no hot reload |
npm run typecheck | Check TypeScript |
npm run build | Bundle the plugin and local engine resources |
npm run package | Complete package, archive, checksums, and provenance |
npm test | Run Vitest after packaging |
npm run test:browser | Check both UI languages in Chromium |
npm run check | Run the complete code validation sequence |
npm run docs:build | Build this bilingual static handbook in output/docs |
npm run docs:preview | Rebuild and serve a local handbook preview |
npm run install:local -- --dry-run
npm run install:localDevelopment uses chess-coach-local and native Codex installation, without a Python installer. Annotated v0.2.0-rc.N or v0.2.0 tags trigger three-platform checks and a Draft Release; manual promotion advances the release branch. Ordinary main pushes never publish a plugin.
Original code, documentation, and artwork use Apache-2.0. Stockfish 18.0.8 retains GPL-3.0; complete packages include dependency licenses, corresponding source, network data, build instructions, and pinned hashes. Incomplete source materials block a release.