Version: 0.5.12 Last Updated: August 2026
AIChessGM is a comprehensive chess database and analysis application for macOS, designed for chess players who want to study games, analyze positions, build opening repertoires, and improve their skills through structured training.
AIChessGM.com included.otb trees,
merge book data, and split by openingAIChessGM combines a native Swift application layer, SQLite-backed storage, external UCI engines, optional AI services, and a Documents-based workspace on disk.
SwiftUI App (Swift 6)
-> AppState + ViewModels + Services
-> SQLite-backed game storage (.cgmdb)
-> UCI engine processes (Stockfish/lc0/etc.)
-> Optional AI provider integration (chat, annotations, vision)
-> Filesystem workspace (~/Documents/AIChessGM).cgmdb) -
Optimized database format for fast loading.bin) - Opening book
format.ctg) - ChessBase opening
book format.otb) - AIChessGM
repertoire builder format.csv) - Supported for
local puzzle training (Lichess and Repertoire Scan exports)If you’re new to AIChessGM, these are the quickest high-value setup steps.
1) Set up your MyGames database - Use Database → MyGames → Create Default MyGames to create the default personal database. - If you already opened a database you want to treat as your personal library, choose Database → MyGames → Set Current Database as MyGames. - Open it anytime via Database → MyGames → Open MyGames. - When no database is active, Game → Add to Database… and Game → Paste PGN and Add to MyGames automatically target MyGames.
2) Configure a UCI engine (Stockfish recommended) - Open Engines → Engines Manager… (⇧⌘,) - Click Add Engine, then select the UCI engine executable (example: Stockfish). - Optional tuning: Threads, Hash Size, and MultiPV for analysis depth.
AIChessGM now includes a built-in Stockfish install helper in the Browser pane.
.tar file by mistake, extract it
first and choose again.You can also use these manual helper actions from the same Stockfish menu: - Download Apple Silicon Build (download only) - Use Downloaded Stockfish… (manual select/configure) - Open Engine Settings… (jump directly to engine configuration)
Because chess engines are standalone executables, macOS may block them the first time you run them. This is normal for unsigned or newly downloaded apps.
If macOS blocks the engine:
stockfish
executable and choose Open, then click
Open in the confirmation dialog.Only override these warnings for engines you trust, and only from sources you recognize.
3) Set up AI assistant access (optional) - Open Settings… → AI. - Choose a provider and paste your API key. - If a key is missing, the AI chat pane will prompt you to configure one.
4) Open or create a working database - File
→ New Database… (⌘N) or Database → New
Database… (⇧⌘N) to create a new collection. - File →
Open… (⌘O) to open an existing database or PGN. - For large
PGNs, AIChessGM can convert to .cgmdb for faster
browsing.
5) Open opening books (optional) - Use an Opening
Book pane’s Open Book control to load
.bin, .ctg, or .otb files when
you want book-assisted play and opening prep. File →
Open… (⌘O) also opens .bin and .ctg
books into the generic Opening Book pane. - Use Settings →
Folders if you want AIChessGM to scan a custom Opening
Repertoire root or separate White/Black repertoire roots
automatically.
Note: AIChessGM requires at least one database to be active. MyGames is a good default if you’re unsure.
Open Settings → License to review the current license state, trial expiration, and activation status.
Open Settings → License to review the capability policy directly. The lists in that pane are generated from the same centralized policy used by the app.
Available in restricted mode:
Unavailable in restricted mode:
For development testing, launch with
swift run AIChessGM --force-restricted-mode or set
AICHESSGM_FORCE_RESTRICTED_MODE=1. This override is
temporary and never changes the stored trial or paid-license record.
Databases are the foundation of AIChessGM, storing your game collections, analysis, and annotations.
Method 1: File Menu - Go to File → New Database… (⌘N) - Enter a name and optional description - Choose a save location
Method 2: Database Menu - Go to Database → New Database… (⇧⌘N)
Validation: Database names cannot contain:
/ \ : * ? " < > |Canonical location: Use File → New Database… as the primary entry point. Database → New Database… is an alternate path to the same action.
You can open databases and chess files in a few ways:
Supported items include:
.pgn) — opened as a
database-backed PGN database.cgmdb) —
fast-loading AIChessGM database format.bin,
.ctg, .otb) — loaded into the Opening
Book/Tree systemTip (large PGNs): When opening a large
.pgn(roughly > 20 MB), AIChessGM may offer to convert it to a.cgmdbdatabase for faster opening and browsing.
From PGN Files:
Tip: For large PGN files (100,000+ games), the import may take several minutes. You can continue using the application during import. Canonical location: Use File → Import… for standard file imports. Database → Import PGN File… is provided for database-centric workflows.
Quick Search: - Database → Search Games… (⇧⌘F) - Enter a search query (player names, openings, ECO codes)
Position Search: - Database → Find Position - Searches for games containing the current board position
Database Browser: - Database → Open Database Browser (⌘D) - Browse all games in the active database - Filter by player, opening, date, result, etc.
Rating Filters: - Database → Filter… → By White Rating… keeps games where White’s Elo is at least the value entered. - Database → Filter… → By Black Rating… keeps games where Black’s Elo is at least the value entered. - Run a split command while a database filter is active to split only the currently visible games.
Download Opponent Games from Lichess or Chess.com: - Database → Download Opponent Games… - Paste a Lichess/Chess.com username or profile URL - AIChessGM auto-detects the site and prefills the username - Choose whether to import into the current database or a new dedicated opponent-prep database - Filter by date range, rated-only, time class, and max games before importing - Imported online usernames are also saved to PlayerInfo.json so the Players pane can show, search for, reopen, and re-download those profiles later
Filter by Current Opening Tree: - Open or build a
tree in the Repertoire Builder pane first. - In the
database pane, run Database → Filter… → By Current Opening
Tree… - Enter a minimum matched ply count such as
6. - AIChessGM keeps only games whose main line stays
inside the currently open tree for at least that many plies. - If you
already filtered the database first, for example by player name or date,
this command refines the current filtered set instead of starting
over.
This is especially useful for opponent preparation: - Filter a large opponent game file down to recent games. - Open your intersected or side-specific repertoire tree in Repertoire Builder. - Apply By Current Opening Tree… to keep only games that actually reached your prepared opening family.
Export Single Game: - File → Export… (⌘E) - Choose PGN, FEN, or JSON format - Select destination (file or clipboard)
Export Entire Database: - Database → Export Database… (⇧⌘E) - Exports all games to a single PGN file
Split MyGames by Opponent: - Database →
Split Database By Opponent… - Enter the names and online
usernames that identify you in PGN headers. - AIChessGM creates a
sibling {Database} Split By Opponent folder with one PGN
per opponent plus split-database.json. - Open and work in
an opponent PGN when you want a smaller, faster game list. - Saving a
split opponent PGN also syncs that shard back into the parent
MyGames.pgn. - Use Database → Merge Split Database
Into Parent… to rebuild the parent PGN from all split files. -
If a database filter is active, only the visible filtered games are
split.
Split a Database by Opening: - Database →
Split Database By Opening… - AIChessGM saves the selected PGN
database, classifies each game with the same deepest ECO opening labels
used by Split Repertoire by Opening…, and writes one
PGN per opening. - The generated sibling folder is named
{Database} Split By Opening and includes
split-database-openings.json. - Games that do not match an
opening label are written to Unclassified.pgn. - If a
database filter is active, only the visible filtered games are
split.
Split a Database by Player Color: - Database
→ Split Database By White Player… creates
{Database} Split By White Player. - Database →
Split Database By Black Player… creates
{Database} Split By Black Player. - Each generated folder
contains one PGN per player listed in that header color and a
side-specific manifest. - If a database filter is active, only the
visible filtered games are split.
ECO (Encyclopedia of Chess Openings) codes identify chess openings.
Add ECO Codes Automatically: - Database → Add Missing ECO Codes… - Scans games and adds ECO codes based on opening moves - Option to overwrite existing codes
Warning: If the current game has unsaved changes, you’ll be prompted to save first.
Click and Drag: 1. Click on a piece 2. Drag to the destination square 3. Release to complete the move
Click to Select: 1. Click on a piece (it highlights) 2. Click on the destination square
Promotions: - When promoting a pawn, a dialog appears to select the piece (Queen, Rook, Bishop, Knight)
Move Validation: - Only legal moves are allowed - Illegal moves are rejected with visual feedback - The engine automatically handles castling and en passant
Keyboard Shortcuts: - First Move: ↑ (Up Arrow) or ⌘↑ - Previous Move: ← (Left Arrow) or ⌘← - Next Move: → (Right Arrow) or ⌘→ - Last Move: ↓ (Down Arrow) or ⌘↓
Menu Options: - Game → First Move - Game → Previous Move - Game → Next Move - Game → Last Move
Undo/Redo: - Undo Move: ⌘Z or Edit → Undo Move - Redo Move: ⇧⌘Z or Edit → Redo Move
Edit Headers: - Game → Edit Header… - Modify player names, event, site, date, round, result, ratings, etc.
Save Game: - Save Game: ⌘S or
Game → Save - Save Game As…: ⇧⌘S -
Save Position as Puzzle…: Game → Save Position
as Puzzle… - Creates a local puzzle row from the current board
position and current best line. - Lets you append to an existing puzzle
CSV or create a new one. - Starts in your configured Puzzles
Folder and suggests saved_positions_puzzles.csv
for new files.
Engine line insertion: - Game pane → Insert Engine Line inserts the current best line from the Analysis pane into the game. - If the current line has no move ahead, the engine line is appended to the main line or active variation. - If a move already exists ahead of the current position, the engine line is inserted as a variation at that position.
AIChessGM supports three different export styles for a game, depending on whether you want raw chess data, a printable study sheet, or a web page.
PGN export: - File → Save Game As…
saves the current game as a .pgn file. - File →
Export… exports the current game as PGN as well. - Use PGN when
you want maximum compatibility with chess databases, engines, and other
chess software.
PDF export: - File → Save Game As PDF… - Game pane → Save As PDF - Exports the current Game pane view as a paginated PDF, including: - player/event metadata - AI comments and narration shown in the Game pane - full rendered variations - print-oriented typography, headings, and page numbers - Use PDF when you want something readable for study, printing, coaching, or email attachments.
HTML export: - File → Save Game As
HTML… - Game pane → Save As HTML - Exports the
current Game pane view as a self-contained
.html document for web publishing. - The HTML export
includes: - the same rendered comments and full variations used in the
Game pane export pipeline - built-in CSS styling so the file can be
opened directly in a browser - hash anchors for moves/comments/NAGs,
making sublinks possible on a website - embedded export metadata in JSON
plus data-export-* attributes for site integrations - Use
HTML when you want to publish AI annotations on a website, share a
browser-readable file, or build links directly to specific comments.
Other sharing options: - File → Email Game… prepares an email with the game attached as PGN. - File → Print… prints the current game with diagrams.
Flip Board: - Game → Flip Board (⌘F) - Toggles between White’s perspective (bottom) and Black’s perspective
Set Up a Position: - Edit → Set Up Position… - Allows custom position setup (useful for puzzles and exercises)
Copy/Paste FEN: - Copy Position (FEN): ⇧⌘C (Game → Copy Position (FEN)) - Paste Position (FEN): ⇧⌘V (Game → Paste Position (FEN))
Use Case: Copy a position to share or analyze elsewhere, or paste a FEN from a puzzle site.
AIChessGM can run a timed game against a UCI engine using your current board UI, with an in-game clock overlay and optional opening book support.
The setup dialog includes an Opponent Preparation section:
The setup dialog includes an Opening Books section:
.otb at game start and uses that
smaller file for engine book moves. If the engine plays Black, AIChessGM
chooses from White split files; if the engine plays White, it chooses
from Black split files. This is available in Engine
Strength mode; Specific Opponent keeps it off
because the open database is the move source for that game..otb tree. Enable Use a random split
file for comparison to load one smaller split tree instead of
the full default repertoire. If you leave the loaded tree, AIChessGM
comments with the approved alternatives and explains why the main tree
move may be better when the tree has evaluation or game-count data.The setup dialog now includes an AI Commentary section for live coaching while you play:
play_engine_mistakes.csv under your configured Puzzles
folder.~/Documents/AIChessGM/Databases/MyEngineGames.pgn, with
captured AI review comments embedded in the PGN.How it works:
Notes:
When a game is active you’ll see a compact overlay with:
When the game ends (checkmate, stalemate, time, repetition, etc.), you can:
AIChessGM can run two UCI engines against each other with independent strength, book, and time-control settings. This is useful for testing engine options, comparing books, and generating training games.
.bin,
.ctg, or .otb book file and set
Priority (Prefer Book / Prefer Engine / Weighted
Blend).The Engine vs Engine pane shows engine names, clocks, and game status. Controls include: - Pause/Resume - Stop - Declare Draw - Save to Database (available after the game ends)
Chess engines provide computer-assisted analysis, evaluating positions and suggesting the best moves.
/usr/local/bin/stockfish)Recommended Engines: Stockfish (free, very strong), Leela Chess Zero (neural network-based)
Start Analysis: - Analysis → Start Engine Analysis (⌘A) - The engine begins evaluating the current position
Stop Analysis: - Analysis → Stop Engine Analysis (⇧⌘A)
Analysis Pane: - Analysis → Toggle Analysis Pane (⌘1) - Displays: - Evaluation score (in pawns or centipawns) - Search depth - Nodes searched - Principal variation (best line of play) - Multiple PV lines (if MultiPV is enabled)
Engine Console: - Analysis → Show Engine Console (⌘2) - Shows raw engine output (for debugging)
Evaluation: - +2.5: White is better by approximately 2.5 pawns - -1.2: Black is better by approximately 1.2 pawns - M5: Mate in 5 moves - 0.0: Equal position
Depth: - How many moves ahead the engine has searched - Higher depth = more accurate but slower
Principal Variation (PV): - The best sequence of moves according to the engine - Click on moves to explore the line
When enabled, arrows on the board indicate the engine’s recommended moves.
Use Compare Pieces for Exchange to estimate which of two opposing pieces is contributing more to the current position and whether trading them would generally favor one side.
This is a counterfactual planning estimate, not proof that a capture sequence works tactically. A real exchange can change because of move order, recaptures, checks, zwischenzugs, or pawn-structure changes. Mate-level or extreme evaluations use WDL when available and otherwise report the comparison as inconclusive.
Use Compare Piece Locations to estimate whether one exact piece would serve its side better on a different square while keeping the current side to move in both engine searches.
Kings are supported, but the alternate board must remain legal. Bishops must stay on their original color complex, and pawns may be compared with earlier squares to ask whether they would have been better left back, but cannot be placed on the first or eighth rank. This holds the rest of the current position fixed; it does not rewind the game. Castling or en-passant state is cleared when the relocation makes it impossible.
Use Show Tactical Tension to find pieces with the same nonzero number of legal attackers and defenders. These balanced contact points are often where adding one attacker, removing one defender, or changing the capture order creates a tactical plan.
Pinned pieces that cannot move without exposing their king are not counted as legal attackers or defenders. A king counts as a defender of every adjacent friendly piece; the static exchange then checks whether its actual recapture is legal after the attacking piece moves. The value-aware result follows captures and newly revealed x-ray attacks on the target square, and either side may stop exchanging when continuing would worsen its material result. The calculation is immediate and does not use the chess engine.
This is a static exchange estimate, not a complete tactical proof. It does not search checks, intermediate moves, mating threats, or captures on other squares. Use it to identify promising planning questions, then verify concrete variations with engine analysis.
AIChessGM requests W/D/L output by default whenever the selected UCI engine advertises support for it. Engines without WDL support continue normally with evaluation-only analysis.
To chart a game’s saved WDL history:
The chart plots White win, Draw,
and Black win percentages after each analyzed move. The
horizontal axis uses chess move numbers. Enable Show
decisiveness to add 100% − draw chance, which
makes sharp transitions easier to spot. If the chart reports no WDL
data, analyze the game again with an engine such as Stockfish or Lc0
that exposes UCI_ShowWDL.
For tactical PDF diagram puzzles, you can prefer Stockfish over Lc0:
Behavior:
AIChessGM can turn board play into a narrated video suitable for sharing, review, or posting.
Open it from:
AIChessGM renders each move frame, generates narration for selected content, and writes the final video.
1080x1080).MP4 or MOV.[%aiError])[%ai])AIChessGM uses
NSSpeechSynthesizerfor reliable local file-based text-to-speech on macOS, and can also use ElevenLabs or Voice.ai for more natural cloud narration during video export, synced PDF audio, and play-vs-engine spoken commentary.
If you want the easiest setup, keep narration on System (macOS) and skip cloud voice providers entirely. See AI and Voice API Setup for a novice-friendly account and API walkthrough.
Use Settings → Video to control defaults used by Game → Save Video…:
720, 1080,
1440)MP4 (.mp4) and
MOV (.mov)The Video Moments pane is a planning workspace for turning selected chess moments into short narrated clips or a longer recap video. It is separate from Game -> Save Video…: the export sheet renders one game or timeline, while Video Moments lets you collect, filter, edit, queue, and generate clip drafts from multiple moments.
Open it from:
Each moment card can include:
Use the top controls to narrow the list:
The summary chips show the total moment count, queued count, and category counts.
For each moment:
Queued moments keep their order when you build a recap draft.
Use Delete All in the pane header to remove every saved video moment after confirmation. This clears the Video Moments list and recap queue, but it does not delete exported video files from disk.
Open Draft Preview on a moment card to inspect the generated clip title, line, intro narration, outro narration, and clip shape. You can edit:
Click Save Script to store overrides on that moment. Click Reset to restore the generated text.
Use Alternative Video Builder -> Create From Current Game when the current analyzed game has stored best-line alternatives. AIChessGM creates moments that show the played move, branch into the stronger engine line, and then return to the game.
If the button is disabled, run Analyze Games or another analysis workflow that stores best-line variations first, then reopen Video Moments.
After queuing moments, click Build Recap Draft. The pane creates:
From the recap draft area you can:
Click Generate Clip on a moment card to prepare the board video export sheet for that moment. Analysis-alternative moments need both a playable main line and an alternative line before clip generation is enabled.
AIChessGM can compute position features, move features, and higher-level motifs (recognizable strategic/tactical patterns). There are now two distinct ways to use feature analysis:
Both workflows surface in the Features Pane, and selected motifs can be examined in the Motif Pane.
Use Analysis → Analyze Current Position Features when you want to understand a single board state rather than the whole game.
This is best for:
What it does:
Important behavior:
Use Analyze Game Features (Current Game) when you want a durable feature/motif snapshot for the active game.
This workflow:
AIChessGM also exposes Analyze Game Features (Background) as a separate menu entry for the same full-game workflow.
The Features pane now has two related but different layers:
The Current Position Analysis section can show:
For a game that has full-game feature data, the pane also includes:
The Strategic Signals section can also use the current-position snapshot directly, so board highlights and explanations can work even when you have not yet run full-game feature analysis.
Current-position motifs are different from full-game motifs:
When a current-position motif provides square or piece evidence, you can:
Examples of current-position motifs that can produce board highlights include:
In supported pawn endgames, current-position analysis can also show a Corresponding Squares card backed by tablebase verification. Matching numbers identify White and Black king squares that answer one another while preserving the tablebase result. From the card you can:
The Motif pane can now show either:
For any selected motif, the pane can show:
For motifs coming from full-game analysis, the pane can also show:
For motifs coming from current-position analysis, the pane shows the motif as a snapshot of the current board. Game-history sections are intentionally omitted because they require saved move history and span-based motif data.
The Motif Catalog is broader than the per-game motif list. It now includes both:
Study topics can have subtopics. For example:
ImbalancesPiece-Quality Imbalances and
Material ImbalancesBishop vs Knight,
Opposite-Colored Bishops, Bishop Pair, and
Rook vs Two Minor PiecesPawn Sacrifices,
Exchange Sacrifices, Piece Sacrifices, and
Queen ImbalancesNimzo-Indian Pawn StructuresNimzo-Indian Rubinstein Structuresc-pawns, IQP,
opposite-flank play, and majority structuresWhen you click a study topic in the catalog:
If you use motif resources heavily, AIChessGM now also supports a dedicated Motifs Folder under Settings → Folders. The motif resource picker opens there by default, making it easier to keep PDFs, PGNs, videos, and OTB study trees organized in one place.
The Current Game section in a study topic is a cross-reference, not a perfect opening-family detector. It uses related detected motifs already present in the engine, so treat it as a useful approximation rather than proof that the active game belongs to that exact study topic.
Use this flow to identify motifs that are strongly linked to your errors:
In the Database pane, you can filter games by motifs (games without analyzed features will not match):
You can analyze features for many games at once:
Named Layouts allow you to save different workspace configurations and switch between them instantly. This is useful when you want different setups for different tasks—analysis-focused, database browsing, training, or any custom arrangement.
Each named layout preserves: - Pane positions: Which panes are where in the dockable workspace - Pane sizes: Column widths, bottom row height, and vertical splits - Pane order: The sequence of panes in each column and row - Window size: The main window dimensions (optional) - Tab groups: Any pane groupings you created
The layout is saved to your user preferences and persists across app launches.
Quick Load: - Window → Load Layout and select from your saved layouts - You can also use the submenu to quickly access frequently used layouts
Auto-Load on Startup: You can configure a layout to load automatically when AIChessGM starts: 1. Go to Window → Load Layout → Auto-load on Startup 2. Select your preferred layout (or “None” to disable) 3. The selected layout will be applied every time you open the app
~/Library/Application Support/com.aichessgm.aichessgm/saved_layouts.jsonAnalysis Setup - Board (left), Analysis (center), Engine Output (right top), PGN (right bottom) - Good for deep position analysis with engine feedback
Database Research - Board (left), Database (center), Game List (right), Filters (bottom) - Optimized for browsing and searching through games
Training Focus - Board (left), Training (center), Notes (bottom) - Minimal layout with just the essentials for practice
Opening Preparation - Board (left), Repertoire Builder (center), Book Moves (right), ECO Browser (bottom) - Maximum opening-related tools in one view
If you want to restore the original layout: - Window → Reset Layout (⌥⌘R) - This restores the bundled default layout
Game Flow Mode is a powerful visual analysis tool that helps you understand how Grandmasters maneuver their pieces during a game. By displaying the complete journey of each piece from a starting position, you can quickly grasp strategic plans and piece coordination patterns.
When enabled, Game Flow Mode tracks and displays:
Each piece is color-coded by its original color (white or black), making it easy to track both sides’ plans simultaneously.
Game Flow Mode captures the current position as the starting point when you enable it. If you click a move in the Game pane while Game Flow is active, it stays in Game Flow mode and re-anchors from that new current position. Selected pieces are preserved by exact identity across position changes (for example, one specific knight stays selected, not both), and only drop out if that piece is captured. As you navigate through the game using the move navigation buttons or keyboard shortcuts, the visualization updates to show all piece movements from that captured position.
ShowVariationsAsPlan (shown in the UI as Show
Variations as Game Flow) lets you preview a variation line with
the same chip-and-path visualization used by Game Flow Mode, without
turning Game Flow Mode on.
When enabled:
Typical use:
Repertoire Flow from Current Position lets the board
use the current Repertoire Builder .otb position as the
source of Game Flow paths. Instead of following one game line, AIChessGM
walks the repertoire branch lines from the current position and shows
what a selected piece or pawn does across those lines.
Typical use:
.otb file in Repertoire BuilderFor a live board preview of the Flowchart, switch Repertoire Builder to Flowchart and enable Repertoire Flow from Flowchart above the chart. Hover over a move card to narrow the board paths to that branch, move away to restore the full flow, or click a branch dot to lock it. See Table and Flowchart Displays below for details.
Repertoire Flow can be used while Repertoire Builder is importing or evaluating branch moves. As new nodes are added, the board overlay refreshes from the current Repertoire Builder position, so you can watch the repertoire tree grow spatially instead of waiting for the operation to finish.
Useful controls in the Game Flow menu:
In Repertoire Builder’s Import menu, turn on Auto Show Repertoire Flow During Import to have engine-line imports prepare the overlay automatically. AIChessGM enables Repertoire Flow, shows all pieces, sets the depth to the import ply range, and widens Rep Flow Moves/Position enough to include the imported candidate moves. For plies 2-* imports, it also accounts for the existing first-ply moves already present at the current position.
Click any move-number marker in Repertoire Flow to jump the
Repertoire Builder and board to that exact branch position. The clicked
marker carries the branch position, so the board loads that position and
Repertoire Builder selects the matching node when it exists in the
loaded .otb.
This is useful in complicated structures where one move order is not enough to explain the plan. For example, you can select a pawn to see which lines push it, leave it fixed, or lose it; select a knight to see its common reroutes; or select a king/rook to compare castling and rook-lift patterns across the repertoire.
Notes:
.otb
modelImportant Squares Submode lets you focus Game Flow on moves that interact with critical squares.
When enabled:
How to use:
Notes:
Selecting Individual Pieces
You can click on any piece’s starting square to toggle its path display. This is useful when: - You want to focus on a specific piece’s journey (e.g., “How did this knight reach that outpost?”) - The board becomes too cluttered with all paths visible - You’re analyzing how two specific pieces coordinate (e.g., bishop and knight pairing)
Navigating to Any Point in a Path
Click on any marker (circle or X) to jump directly to that position in the game. This allows: - Quick inspection of intermediate positions - Verification of tactics at capture points - Understanding the timing of strategic maneuvers
Clearing the Starting Position
To capture a new starting position: 1. Move the board to your desired starting position 2. Toggle Game Flow Mode off and on again
The capture happens automatically when you enable Game Flow Mode. While it is active, navigation in the Game pane re-anchors the flow from the new current position.
Understanding Opening Plans
Start Game Flow Mode at move 10-15 and watch how: - Bishops develop to active squares - Knights find optimal outposts - The queen coordinates with minor pieces - Pawns create strategic structures
Analyzing Middlegame Restructuring
A strong mid-game plan often involves: - Knight relocations to better squares - Bishop pair activation after pawn moves - Rook penetration on open files - Queen centralization
Game Flow Mode makes these patterns visually obvious.
Studying Endgame Technique
Endgame studies become clearer when you can: - See exactly how the king approached the opposition - Track passed pawn advancement - Observe rook activation patterns - Understand piece sacrifice timing
Opening books provide pre-analyzed opening moves based on master games and theory.
.bin and
.ctg books into the generic Opening Book pane and adds them
to recents..bin (Polyglot), .ctg
(ChessBase), or .otb (Repertoire Builder) fileAIChessGM also supports side-specific books via the Opening Book — White and Opening Book — Black panes. Use each pane’s Open Book control or Recent Opening Books submenu to switch that side directly without maintaining a library list.
Where to Find Books: - Polyglot books: Available online (search “polyglot opening book download”) - ChessBase books: Bundled with ChessBase products
Viewing Book Moves: - The Opening Book pane displays available moves with statistics: - Polyglot: Weight (frequency of play) - CTG: Number of games, win/draw/loss percentages, performance rating
Filtering Options:
CTG Books: - Game Percentage Threshold: Show moves played in at least X% of games (default: 10%) - Performance Percentage Threshold: Show moves with at least X% performance (default: 2%) - Minimum Game Count: Minimum number of games required
Polyglot Books: - Weight Threshold: Shows all moves, weighted by frequency
For a dedicated manual focused entirely on this feature, see the Repertoire Builder Guide.
The Opening Tree is the fastest way to build, analyze, and train a real repertoire from your own games and reference databases. Unlike a static opening book, it’s built from your data, updated anytime, and it understands transpositions, so the same position is always tracked as one node no matter how you reached it.
Via Menu: - Workspace → Repertoire Builder Pane (⌘⇧7)
Via Toolbar: - Click the Repertoire Builder icon in your pane toolbar
The pane works in conjunction with your open database. If no database
is loaded, you’ll need to build a tree first or open an existing
.otb file.
.pgn file.otb fileThe pane displays move statistics for the current board position. Each row represents a legal move, showing:
| Column | Description |
|---|---|
| Move | SAN notation of the move |
| Plays | Number of games with this move |
| % | Percentage of total games at this position |
| W | Win % for side to move |
| D | Draw % |
| L | Loss % |
| Avg Elo | Average player rating |
| Eval | Engine evaluation (if analyzed) |
| Score | Combined quality score |
Click any move to play it on the board and update statistics. Click a column header to sort by that metric. Use the search field to filter moves by notation or name.
Use the Table / Flowchart selector in the
upper-right corner of Repertoire Builder to change how the current
.otb position is displayed. AIChessGM remembers the
selected display for the next time you open the pane.
The lower bar in Repertoire Builder is the fastest way to work position-by-position:
Use AI Go To to jump directly to positions that need attention:
This is useful for cleanup passes when you want to fix only unresolved or inconsistent positions.
Fix Queue side awareness: when the loaded repertoire file is recognized as side-specific (for example a known White or Black split repertoire), Fix Queue suppresses opposite-side multi-move/missing-eval items. Eval/backsolve mismatch candidates are still included.
You can run engine analysis directly on positions in your tree.
The engine will analyze each position, and results appear in the Eval column.
Smart Analysis only analyzes positions that need it—those without existing evaluations or with evaluations below a quality threshold:
This is much faster than full batch analysis for large trees.
In addition to one-click Analyze Tree and Analyze Branch…, use:
Backsolving propagates evaluations from analyzed child positions upward:
Even if you haven’t analyzed a parent position, AIChessGM can estimate it from analyzed child positions so your tree is never full of blanks.
This fills gaps in your analysis quickly.
You can run three backsolve modes from the pane:
Focus analysis on a specific line:
Only positions in that line are analyzed, saving time.
Fine-tune what you see in the tree:
Enable Filters: - Toggle Display Filters in the pane toolbar - Set minimum plays (hide rarely played moves) - Include/exclude unknown results
Common Filters: - Hide moves with < 10 plays to focus on main lines - Show only moves with > 50% win rate - Filter by minimum average rating
Import ChessBase book statistics:
.ctg file (and companion files if
required)Statistical data from the CTG book is merged into your tree.
Merge or replace statistics from another .otb file:
.otb fileThis lets you combine multiple sources or update a tree with new data.
Import engine evaluations from analyzed games into your tree:
Evaluations from your database games are added to tree positions.
You can also export tree evals back to games from the same Sync menu:
You can rename moves for clarity:
This is useful for remembering “that move where Carlsen surprised everyone.”
Remove unwanted lines:
The entire subtree below that move is removed.
Automatically add moves you play on the board to the tree:
This lets you build a tree from your own games as you play.
The Tools menu in Repertoire Builder includes advanced workflows:
Include WDL with Repertoire Analysis and Show Repertoire WDL are enabled by default in the Repertoire Builder’s engine-line settings. Compatible engines store White/Draw/Black estimates alongside the centipawn evaluation during engine-line import and Analyze Move. Engines without WDL support continue with evaluation-only data, and WDL never replaces or changes the centipawn-based move ranking.
You can turn either setting off when you do not want WDL requested or when you want to hide the WDL column without deleting stored values.
With a Repertoire Builder tree open, choose Tools → Create Chessable Input Package…. AIChessGM first validates the export and presents an author-review preview. After you approve it and choose a destination folder, the package contains:
chapters/course-manifest.json describing chapter order and
exported linesREADME.md with import guidanceAUTHOR_REVIEW.md identifying material that should be
checked before course publicationExisting Repertoire Builder comments are preserved as PGN comments. The package prepares source material for author review and Chessable import; it does not upload or publish a course.
One of the strongest Repertoire Builder workflows is using a single
source repertoire as your master tree, then splitting it into distinct
.otb files for each major opening.
This is useful when: - One large repertoire has become too broad to review comfortably in a single file - You want separate engine-analysis progress for openings such as the Sicilian, French, Caro-Kann, Queen’s Gambit, and so on - You want to archive fully analyzed opening trees without losing track of later edits - You want owner-side auto-load and scan tools to match the most specific split file available
The important idea is that a split folder is not just a convenience
export. It becomes a structured repertoire workspace: each opening gets
its own live .otb, while the split folder as a whole keeps
a shared record of analysis coverage and analysis integrity.
The Repertoire Builder integrates with Training Mode:
The tree becomes your training partner, testing you on moves from your database. Repertoire Training continues through trainer replies and child moves until a leaf node is reached (or your depth limit is reached).
Repertoire Training behavior: - Uses the Repertoire Builder tree plus
the board, game, and training panes (not the live database provider). -
Validates your move against the exact pre-move board position before
accepting or rejecting. - Auto line-complete releases training lockouts
immediately, while keeping End/Restart
controls available. - Stepping backward/forward in the Game pane rebinds
Repertoire Builder lookup to that new position. - Repertoire Builder
remembers the last opened .otb and auto-loads it when the
pane opens (unless a rule requests a different tree). - Opening a
side-associated repertoire (including side-detected split files)
auto-orients the board so that side is on bottom.
Book vs Book Training: - Load White and Black repertoire builders - Select Book vs Book in Training Mode - Practice both sides of your repertoire
Saving Your Tree: - Click Save in the pane toolbar, or Openings → Save Tree - Use Save As to create a new file
Automatic Backups: When you save, AIChessGM creates timestamped backups:
MyOpenings/
├── Backups/
│ ├── MyTree.otb.20250110-211849.bak
│ └── MyTree.otb.20250109-153022.bak
└── MyTree.otbBackups/ folder if it exists next to
your .otbQuit Prompt: If you have unsaved changes, you’ll be prompted to save when quitting.
Export your analyzed tree back to a database:
This creates a new database containing all positions from your tree.
Building Your Repertoire Tree: 1. Create a database of games with your preferred opening lines 2. Build a tree from just those games 3. Use filters to hide opponent’s rare responses 4. Analyze the main lines 5. Export to training mode
Preparing for a Specific Opponent: 1. Use
Database → Download Opponent Games… to pull the
opponent’s recent games from Lichess or Chess.com into the correct
database. 2. In the Players pane, use the Lichess or
Chess.com fields to find likely usernames, then save, clear, open, or
re-download that opponent’s online profile later. 3. Filter the opponent
database by player and date range. 4. Build or open the relevant
side-specific/intersected .otb in Repertoire Builder. 5.
Run Database → Filter… → By Current Opening Tree… with
a threshold such as 6 plies. 6. Review only the games that actually
reached your expected opening. 7. Train from the resulting intersected
tree or filtered game set.
Open the Matching Black Split Tree from the Active
Game: 1. Keep the target game loaded as the active game. 2. In
Repertoire Builder, click Black Split.
3. AIChessGM resolves the active game’s opening against your configured
Black split/intersect tree workspace and opens the best matching
.otb. 4. If the exact opening name is not present as a
split file, AIChessGM falls back to the deepest available ancestor
opening that does exist.
Import TWIC stats and opponent replies into a split
tree: 1. Open a White- or Black-associated split
.otb in Repertoire Builder. 2. Choose Openings →
Import TWIC Opponent Moves…. 3. Select the matching TWIC
opening PGN. 4. AIChessGM verifies the opening match, refreshes stats on
existing moves, and adds only opponent replies below repertoire-owner
moves that already exist.
For White split files, new Black replies can be imported under existing White moves, but new White moves are not imported. For Black split files, new White replies can be imported under existing Black moves, but new Black moves are not imported.
Studying a New Opening: 1. Build a tree from master games (2700+ players) 2. Sort by plays to see the main line 3. Sort by win rate to find successful replies 4. Use branch analysis on critical positions 5. Take notes on key positions
Building a Global Reference: 1. Combine multiple databases (your games, master games, online games) 2. Import CTG book data for additional statistics 3. Run full engine analysis on main lines 4. Save with descriptive name (“Complete_Reference_2025.otb”)
Performance Tips: - For databases with 100,000+ games, build trees incrementally - Use branch analysis on specific lines rather than full tree analysis - Enable display filters to reduce visual clutter - Use Smart Analysis to skip well-analyzed positions
Data Management: - Regularly clean old backup folders if disk space is tight - Consider exporting analyzed trees to databases for backup - Use descriptive names: “My_Sicilian_Defense_2025.otb”
This workflow ties together database scanning, owner-side detection, split repertoires, and puzzle generation.
From the Analysis menu: - Analyze Repertoire (Filtered Games)… - Analyze Repertoire (All Games)…
During setup: - If Owner name is set (Rules tab), matching games auto-detect owner side. - If no owner match is found, the scan uses your selected fallback side (White/Black). - You can skip games already scanned.
Open results using: - Analysis → Repertoire Scan Results… - Or Workspace → Repertoire Scan Pane
The pane shows: - Scan timestamp, players, owner side - Owner and
opponent departure move (ply + SAN/UCI) - Matched
split-tree names/paths for White and Black when available - Full file
paths for base repertoires and matched split files
After a successful repertoire scan, AIChessGM writes: -
repertoire_puzzles_white.csv -
repertoire_puzzles_black.csv
These files are generated in your Puzzles folder (see Default Folders and Generated Files).
repertoire_puzzles_white.csv or
repertoire_puzzles_black.csv.Use Database → Split Database by Player… to split one source database into side-specific outputs.
Generated outputs are named from your player name stem: -
{Player}AsWhite.pgn or .cgmdb -
{Player}AsBlack.pgn or .cgmdb - Optional build
step also creates {Player}AsWhite.otb and
{Player}AsBlack.otb
Use Database → Split Database By Opponent… on a PGN
database such as MyGames.pgn to create smaller
opponent-specific PGNs in a sibling
{Database} Split By Opponent folder. Enter the names and
site usernames that identify you; games where neither side matches are
written to Unknown Opponent.pgn.
The opponent split folder contains split-database.json
and one PGN per opponent. Older {Database} Split folders
are still recognized when merging or reading owner aliases. When
splitting or merging, matching copies of the same game are collapsed and
the richer analyzed/commented copy is kept. When you save an opponent
shard, AIChessGM writes the shard and merges it back into the parent
PGN. Use Database → Merge Split Database Into Parent…
whenever you want to rebuild the parent from all split files.
If the database has an active filter, including Filter… → By White Rating… or Filter… → By Black Rating…, the split uses only the currently visible filtered games. This is useful for creating opponent, opening, or player-color shards from stronger-player games without first exporting a temporary PGN.
Use Database → Split Database By Opening… on a PGN
database to create a sibling {Database} Split By Opening
folder with one PGN per opening. The splitter runs in the background,
uses the same deepest ECO opening identification and filename cleanup as
Split Repertoire by Opening…, and records the generated
files in split-database-openings.json.
Games that do not reach a known split opening are written to
Unclassified.pgn. Opening split files are independent study
shards; they are not automatically merged back into the parent database
when saved.
If the database has an active filter, the opening split uses only the currently visible filtered games.
Use Database → Import TWIC Files Into Split Folders… to build your own GM database from downloaded TWIC PGN files. Other chess programs often ship curated grandmaster databases; this workflow lets you maintain a local equivalent by repeatedly adding TWIC files, filtering for high-rated games, and pre-splitting the result so it stays usable as it grows.
The import creates and updates three maintained split folders in one
operation: - An opening folder, with one PGN per opening plus
Unclassified.pgn - A White-player folder, with one PGN per
White player name - A Black-player folder, with one PGN per Black player
name
Splitting during import avoids the performance and usability problems of one huge PGN. You can open only the opening or player file you need, while the import command keeps merging new TWIC material into the existing split files.
Workflow: 1. Download one or more TWIC PGN files. 2. Choose
Database → Import TWIC Files Into Split Folders…. 3.
Select the downloaded twicNNNN.pgn files. Multiple files
can be selected at once. 4. Enter the minimum rating for both players.
The default is 2600, and AIChessGM remembers the last value you used. 5.
AIChessGM writes to the folders configured in Settings →
Folders: - TWIC Opening Split Folder defaults
to Documents/AIChessGM/Databases/TWIC Openings -
TWIC White Player Split Folder defaults to
Documents/AIChessGM/Databases/TWIC White Players -
TWIC Black Player Split Folder defaults to
Documents/AIChessGM/Databases/TWIC Black Players 6. When
the import completes, the summary shows how many files were selected,
skipped as already included, processed, filtered by rating, routed to
each split type, and written as new or replacement games.
Filtering and routing: - A game is kept only when both
WhiteElo and BlackElo are at least the chosen
minimum rating. - Games missing either Elo header, or with either player
below the chosen minimum rating, are skipped. - Kept games are
identified with the same deepest ECO opening labels used by
Split Database By Opening… and Split Repertoire
by Opening…. - Each kept game is merged into the matching
opening PGN, such as Sicilian Defense.pgn. - Games that do
not reach a known split opening are kept in
Unclassified.pgn. - The same kept game is also merged into
the PGN for its White player and the PGN for its Black player.
Duplicate handling: - Each split folder records imported TWIC source files in its manifest using a SHA-256 file fingerprint. - If you select a TWIC file that has already been imported unchanged into a split folder, AIChessGM skips that file for that folder before parsing it. - If a TWIC file with the same name has changed, the changed file is processed because its fingerprint is different. - Matching games are still deduplicated by game identity. If a matching game already exists in an opening PGN, AIChessGM keeps the richer copy, preferring the version with more annotations, variations, ECO/opening data, or comments.
Output files: - split-database-openings.json records the
opening-file mapping and imported TWIC source fingerprints. -
split-database-white-players.json records the White-player
file mapping and imported TWIC source fingerprints. -
split-database-black-players.json records the Black-player
file mapping and imported TWIC source fingerprints. - One PGN is
maintained per opening. - One PGN is maintained per White player name. -
One PGN is maintained per Black player name. -
Unclassified.pgn is maintained for elite games that pass
the rating filter but do not match a known split opening. - Only split
files touched by the selected TWIC files are reparsed and rewritten, so
weekly imports stay responsive as the folders grow.
Use Database → Split Database By White Player… or
Database → Split Database By Black Player… when the
database is not centered on your own games and you want one PGN per
player appearing on a specific side. White-player splits are written to
{Database} Split By White Player; black-player splits are
written to {Database} Split By Black Player.
These side-specific split folders are independent study shards. They do not use owner aliases and are not automatically merged back into the parent database when saved.
If the database has an active filter, the side-specific split uses only the currently visible filtered games.
In the Repertoire Builder pane, use Split Repertoire by
Opening… to split a source .otb by deepest ECO
opening name.
Output behavior: - Creates a sibling folder named
<SourceStem>-Split - Writes one .otb
file per opening inside that folder - Keeps parent branches needed to
preserve valid tree paths
This split output is also used by owner-side auto-load logic when a matching split file is found.
Example layout:
MyWhiteRepertoire-Split/
├── Sicilian Defense.otb
├── French Defense.otb
├── Caro-Kann Defense.otb
├── split-folder-stats.json
└── Analyzed/
├── Sicilian Defense.otb
└── French Defense.otbUse Repertoire Builder → Tools → Analyze & Smart Merge
Two Split Folders… when two split repertoires reach some of the
same named split positions—for example, independently calculated
1.d4 and 1.Nf3 repertoires that both reach the
King’s Indian Bayonet Attack.
The analysis report is useful by itself. It lists: - Every pair whose named split-position FEN occurs in both repertoires, including pairs with different filenames - Files whose split positions occur only in the primary or additional repertoire - Common and unique position counts inside each matching file - Analyzed-position counts, maximum engine-node depth, stored file depth, and engine identity - Which repertoire supplied the deeper node and move analysis - Compatibility problems that block an unsafe merge
For each common split position, AIChessGM unions the two files’ chess
positions and moves, preserves both move-order paths, keeps the deeper
stored engine analysis as an intact evaluation/node-count pair, retains
the richer statistics record without adding duplicate counts, and
recomputes derived backsolve values. The output contains only these
common split-position pairs. Files unique to either repertoire are
reported but excluded, and INTERSECT helper files are
skipped.
The source folders are never modified. AIChessGM builds a new output
folder transactionally, regenerates split-folder-stats.json
and the Analyzed/ artifacts, and writes the full selectable
inventory to AIChessGM-merge-report.txt. Cancellation or an
error removes the incomplete temporary output.
Every split folder now has a dedicated manifest file named
split-folder-stats.json.
That manifest stores per-file statistics similar to what you see when loading a tree, including: - Total positions - Leaf positions - Analyzed positions - Positions analyzed at or above the deep-analysis threshold - Percent of positions analyzed - Percent of positions analyzed at or above the deep-analysis threshold - Analyzed leaf positions - Analyzed leaf positions at or above the deep-analysis threshold - Snapshot / regression / divergence status compared with archived fully analyzed copies
The current deep-analysis threshold for these split-folder checks is
100,000 engine nodes. In practice, that means the manifest
is tracking not only “has this position been analyzed?” but also “has it
been analyzed deeply enough to count as complete for this workflow?”
Analyzed/ FolderWhen a split tree becomes fully analyzed at the
100,000-node threshold, AIChessGM copies that
.otb into the split folder’s Analyzed/
subfolder.
This gives you two layers of protection: - The live split file continues to evolve as you edit, merge, or reanalyze it - The archived copy preserves a known-good fully analyzed version of that opening tree
If analysis coverage later drops, or if the live file diverges from the archived fully analyzed copy, the manifest records that change so it is visible instead of silent.
The split-folder manifest and analyzed snapshots are refreshed automatically when: - You create a split repertoire - You save a split-tree file - File-backed OTB analysis writes updated analysis into a split-tree file
Open Workspace → Split Tree Stats Pane to inspect a split folder as a whole instead of loading every tree one by one.
Typical workflow: 1. Open the pane from the
Workspace menu. 2. Click Choose
Folder… and select the split folder. 3. Review the summary
chips for total files, snapshots, regressions, divergence, positions,
leaves, analyzed positions, and >=100k positions. 4.
Click any column header to sort by that statistic. 5. Select a row to
inspect the chosen opening tree in more detail.
The pane is designed for repertoire maintenance and integrity
checking. It lets you: - Sort the split set by positions, leaves,
analyzed counts, >=100k counts, percentages, snapshot
presence, regression state, and deep-analysis delta - Reload the folder
to refresh the manifest after new analysis work - Open the split folder
itself in Finder - Open split-folder-stats.json directly -
Reveal the live split file - Reveal the archived fully analyzed snapshot
when one exists
Interpret the integrity columns like this: -
Snapshot: A fully analyzed archived copy exists in
Analyzed/ - Regression: The live file has
lost deep-analysis coverage compared with its archived fully analyzed
copy - >=100k Delta: Difference in deep-analyzed
positions between the live file and the archived copy
For large repertoires, this pane is the quickest way to answer practical questions such as: - Which openings are fully analyzed already? - Which split trees still need deeper engine work? - Did I accidentally lose analysis coverage after editing or merging? - Which opening file should I work on next?
Prepare for Opponent turns an active database into a practical event-preparation workspace. It filters the opponent sample, summarizes tendencies, builds opponent repertoire files, creates intersections with your repertoires, prepares training entry points, and can configure Play vs Engine to play like that opponent.
Use this feature when you have:
.otb files available when
you want intersection trainingThe strongest workflow starts with a focused opponent database or split database, but the feature also works from the active database if the opponent can be selected from the player list.
You can open the workflow in two ways:
From the Players pane, select any player in the active database who is not the owner, then click Prepare. This opens the same workflow with that player selected.
Before running, the sheet shows:
Some steps are marked Later because they are visible in the planned workflow but not fully active in the current release. The currently active preparation path can update opponent repertoire files, build repertoire intersections, create mistake puzzles from analyzed games, enable Play Like Opponent, and summarize opponent tendencies.
After running, the sheet shows a Preparation Dashboard with:
.otb repertoires, and intersection .otb
filesAfter the first dashboard is available, click Begin Preparation Session to run the main preparation bundle for the selected opponent. This automatically includes:
The sheet saves progress to preparation history so recent opponent sessions remain visible in the same dialog.
AIChessGM writes opponent-preparation files under:
~/Documents/AIChessGM/Prepare/<Opponent Name>/Typical outputs include:
filtered-games.pgn: the opponent-filtered sample used
for preparationopponent-white-games.pgn and
opponent-black-games.pgn: side-specific opponent game
exportsopponent-white-repertoire.otb and
opponent-black-repertoire.otb: generated opponent
repertoire treesintersection-your-white-vs-opponent-black.otb: your
White repertoire intersected with the opponent’s Black repertoireintersection-your-black-vs-opponent-white.otb: your
Black repertoire intersected with the opponent’s White repertoireIf mistake puzzle generation is selected, AIChessGM also uses the normal analysis puzzle CSV workflow and copies relevant puzzle artifacts into the preparation folder when possible.
After repertoire intersections or puzzle files are available, the sheet offers direct Training buttons:
.otb as the
student book and the opponent repertoire as the trainer book.AIChessGM opens the Training pane automatically. If another training session is already running, end that session first, then start the prepared training again.
Use Open Play vs Engine from the preparation dashboard, or open Game → Play vs Engine… later.
In the Play vs Engine setup dialog:
Specific Opponent mode uses the database or opponent split as the engine’s opening-response profile, then falls back to normal engine play when there is no suitable opponent move.
The Players pane can store and reuse profile identifiers:
Saving these identifiers makes future preparation faster. When an ID or username is available, Prepare-related flows can open the profile directly or send the saved username into the opponent-game download flow.
Training Mode is a powerful feature for improving your chess skills by practicing move selection with immediate feedback.
The Training pane discovers agents dynamically based on what you currently have loaded (analysis, a game, books, database trees). Common agents include:
.otb books are loaded.Mistake Training lets you practice finding a better move in positions where a player made an Inaccuracy, Mistake, or Blunder.
AIChessGM switches to a temporary scratch training position so your original game is not modified.
The thresholds shown in the Mistake Training settings use your configured centipawn-loss cutoffs:
(These thresholds come from your Analysis settings.)
After analysis is complete, you can generate motif-specific puzzle files and train directly on those motifs.
From the Analysis menu:
Choose which error classes to include (inaccuracies, mistakes, blunders), then export.
AIChessGM writes:
~/Documents/AIChessGM/Puzzles/analysis_puzzles_white.csv~/Documents/AIChessGM/Puzzles/analysis_puzzles_black.csv~/Documents/AIChessGM/Puzzles/analysis_puzzles_motif_summary.csv~/Documents/AIChessGM/Puzzles/MotifTraining/analysis_puzzles_motif_<motif_slug>_white.csv~/Documents/AIChessGM/Puzzles/MotifTraining/analysis_puzzles_motif_<motif_slug>_black.csvAIChessGM automatically points the Puzzle Files (Local CSV) agent at that motif’s CSV and starts the session.
Puzzle training supports both online and local-file workflows.
Online puzzle feeds
Local puzzle files
repertoire_puzzles_white.csv /
repertoire_puzzles_black.csv)analysis_puzzles_white.csv /
analysis_puzzles_black.csv)MotifTraining/analysis_puzzles_motif_<slug>_white.csv
/
MotifTraining/analysis_puzzles_motif_<slug>_black.csv)pdf_diagram_puzzles.csv)From the Training pane (when Puzzle Files / Local CSV agent is selected), you can:
Notes:
Use this when you already have the position on the board and want to turn it into a reusable local puzzle file:
Notes:
saved_positions_puzzles.csv, but you can choose any
.csv name.Use this workflow to convert printed-book diagrams into trainable local puzzles:
17 or 17-24, then click Start Diagram
Extraction.Optional puzzle options:
Output:
~/Documents/AIChessGM/Puzzles/pdf_diagram_puzzles.csvNotes:
Use this workflow when you want the current PDF diagram to become prose in the Game pane:
Notes:
The Extract… tool in the Chess Book (PDF) pane opens a floating review window for both move-text and diagram workflows.
Use Games when you want to pull move text from a page or page range into Scratch or a variation:
13 or 13-19, then click Start Game
Extraction.Use Diagrams when you want AIChessGM to detect a board directly on the PDF page:
Notes:
AIChessGM can also turn a copied puzzle screenshot into a post-ready social blurb:
Notes:
AIChessGM.com.AIChessGM includes optional AI features for explanations, annotations, and automation.
AIChessGM now exposes a set of task-focused AI Skills. These produce stronger, more consistent commentary by narrowing the AI to a specific workflow instead of treating everything as open-ended chat.
Current built-in skills include:
You can access skills from:
Use this skill when you have a player-split database open and one of that player’s games open at the opening position you want to prepare.
The skill detects which color the opponent played in the open game and prepares the opposite color for you. It supplies the selected FEN and opening sequence, asks the engine for best continuations from that position, and separately shows only the opponent’s historical continuations from split-database games that reach the same position. If the Repertoire Builder has a matching split repertoire open, its approved moves at that position are also supplied.
For example, when the opponent played White in the open Scotch Gambit game, the plan is for you as Black. Your suggested Black moves come from engine analysis and the matching repertoire, not from the opponent’s game history; history is used only to identify moves the opponent may choose. The plan always warns when the engine finds a historical opponent move or a loaded repertoire move inferior. A historical mistake is presented as a deviation to exploit; a repertoire mistake is presented as a bad or outdated prepared move together with the engine-preferred alternative. If its prepared response is not in the open repertoire, open the corresponding repertoire split and run the skill again. It does not spend time on your White repertoire, the opponent’s games that do not reach the selected position, or generic opening summaries. If no other split-database game reaches the position, it says so instead of treating unrelated games as evidence.
In addition to move-by-move comments, AIChessGM supports higher-level Ideas annotations.
Note: AI features require an API key (or a configured local model provider, depending on your setup).
This is one of the most intimidating parts of setup for new users, so the first thing to know is:
If you want the lowest-friction setup:
openrouter/free is a good no-cost first chat option; OpenAI
is the better first choice if you also want Whisper voice input.For most novice users, OpenAI is the simplest first cloud provider because it can cover:
Step by step:
Important: A normal ChatGPT subscription does not automatically include API access. API usage is separate from the consumer ChatGPT app/site plan.
Keep your key private: Do not paste an API key into a chat, email, screenshot, game comment, or shared document. Save it only in Settings → AI. If you believe a key was exposed, revoke it in the OpenAI Platform and create a replacement.
Cost control: Start with the default model and short questions. Review usage and spending limits in your OpenAI Platform account before using long game annotations, large document tasks, or frequent vision requests.
OpenRouter is a good first option for chat and AI
annotations when you want to try cloud AI without committing to one paid
model. AIChessGM can use OpenRouter’s openrouter/free
router, which automatically selects an available free model that
supports the request.
Step by step:
openrouter/free for Chat
Model.openrouter/free is great for trying AIChessGM and
low-volume personal use, but it is a router rather than one fixed model.
The underlying model, writing style, speed, availability, and free rate
limits can change from request to request. The Chat header and AI
Diagnostics show the actual model that answered. If you find a model you
like, choose its named OpenRouter model ID for more consistent
results.
Use the engine for chess facts: OpenRouter can write excellent explanations, but AIChessGM’s engine analysis remains the source of truth for tactical claims and best moves.
Key safety: Save the key only in Settings → AI. Do not paste it into chats, screenshots, game comments, or shared documents. Revoke it from OpenRouter if it is exposed.
openrouter/free, choose a named model when you want more
consistent quality, behavior, and availability. Named models may have
usage charges; check the OpenRouter model page before selecting
one.If your goal is simply “try high-quality AI chat with the least
cost,” start with OpenRouter →
openrouter/free. Choose OpenAI
first when you also want its vision or Whisper features.
Use oMLX when you want a model to run locally on your Apple-silicon Mac instead of sending chat requests to a cloud provider. You do not need an AI-provider account or API key unless you choose to configure one inside oMLX. You do need disk space, unified memory, and time to download a model.
Before you start:
Step by step:
.dmg, drag oMLX to
Applications, then launch it from Applications.http://127.0.0.1:8000/v1 unless you deliberately changed
oMLX’s server address.If Refresh finds no models:
http://127.0.0.1:8000/v1.If a model is slow or your Mac reports memory pressure, stop the server, choose a smaller model in oMLX, and try again. Local model performance varies substantially with your Mac’s unified memory and the model size.
For current oMLX installation and model documentation, see the oMLX project guide.
Use MLX if you want AI chat to run on your Mac instead of a cloud API. This is best on Apple Silicon Macs with enough unified memory.
AIChessGM stores MLX models in:
~/Documents/AIChessGM/Models/Starter model guidance:
If a model loads but feels slow or memory pressure rises, choose the next smaller model. If the Chat pane header says Ollama, OpenAI, or another provider, you are not using MLX yet; return to Settings → AI and select MLX.
After a reply finishes, click the AI Diagnostics info button in the Chat AI header to inspect and copy the active backend, model, token counts, generation rate, latency, memory sample, and context usage. These values are useful when comparing MLX models or reporting performance problems.
If voice setup feels frightening, keep it simple:
That gives you voice features without creating any extra account.
Use this only if you want cloud speech recognition and already set up OpenAI:
Use this if you specifically want Wispr Flow’s cloud voice input:
Use this only if you want cloud narration for exported videos:
Use this only if you want Voice.ai cloud narration for exported videos, synced PDF audio, or play-vs-engine spoken commentary:
The Chat AI can look up current information and cite the pages it used.
Search queries are sent to DuckDuckGo. Internet lookup reads only built-in trusted chess/reference hosts and hosts represented by entries in the existing Sites pane. Add or remove custom trusted websites in View → Sites Pane; no second site list is required. AIChessGM uses HTTPS, blocks local/private network addresses and unsafe redirects, limits page size and request duration, and treats downloaded page text as untrusted evidence rather than instructions. Answers based on a lookup should include clickable source links.
Under Settings → AI → Model Settings, AIChessGM supports separate vision models:
This lets you keep diagram recognition fast while assigning a stronger vision model for messy handwriting OCR.
In addition to the Chat pane, AIChessGM exposes several AI actions from the Analysis menu. Common examples:
AI annotations inserted by AIChessGM are typically tagged in the PGN so you can identify them later.
When an engine supplies W/D/L data, AIChessGM treats it as
White win / Draw / Black win percentages (for example,
W24/D52/B24). WDL is requested by default from compatible
engines. Engines that do not report it continue to provide
evaluation-only analysis.
Feature analysis and related AI artifacts are stored under the app’s Application Support folder. You can open it via:
The Rules tab in Settings now includes two layers:
Open it via: - Settings → Rules
Core behavior: - Rules are evaluated in order. - First match wins. - You can reorder rules using up/down controls. - Rules can be enabled/disabled individually.
Rule types: 1. Player name match 2. ECO code range
For player rules, you can define: - Match mode (Exact or
Contains) - Bottom side behavior (matched player at
bottom/top, or force White/Black at bottom)
Set Owner’s name once in Rules settings.
When matched, AIChessGM can infer whether you are White or Black in the
active game and apply owner-relative automation.
Player rules can auto-load repertoires to one of these targets: - Repertoire Builder - Opening Book (by owner side) - Split Repertoire Builder (by owner side) - Opening Book — White - Opening Book — Black
For split workflows, AIChessGM attempts to resolve split assets (for
example, <stem>-Split folders and intersect trees)
and falls back to the base repertoire when needed.
Use Load Starter Bundles (Top 20) to install a built-in starter set with high-impact rules grouped into bundles such as:
Starter bundles are merged non-destructively by rule ID so loading again is safe.
Before enabling a bundle (or Enable All Seed Rules), AIChessGM runs a dry-run preview:
You must confirm the preview before enable actions are applied.
Use these buttons in Settings → Rules:
RulesSettings.jsonThe current snapshot includes: - Auto-orient toggle - Owner name - Full orientation rules list (including repertoire auto-load targets such as Split Repertoire Builder (by owner side)) - Default White/Black repertoire paths - Configured White/Black split folder/tree paths
This is the recommended way to carry your orientation and auto-load setup into a fresh app install.
Orientation rules can also apply analysis defaults automatically: - Mapping mode: White/Black or Owner/Opponent - MultiPV values - Centipawn filter values
This is useful when you want strict settings for your side and wider settings for opponent responses.
Direction for upcoming releases:
Until website pack sync ships, use RulesSettings.json
export/import for manual portability.
Explain Mode is a lightweight onboarding mode for learning the interface before committing an action.
When Explain Mode is enabled and you click a supported pane button or menu command, AIChessGM first shows:
From that explanation sheet you can choose:
Explain Mode is designed to stay fast:
AIChessGM’s workspace uses a dockable pane system for flexible layouts.
.otb) and analysis toolsThe PDF and Position Recognition workflow is optimized for diagram extraction and puzzle creation:
AIChessGM.com
attached.This lets you go from scanned diagram either to a local training puzzle, a diagram-specific teaching comment, or a branded shareable post without manual FEN entry.
Open Workspace → Scoresheet Pane to turn paper scoresheets into a playable game in the Game pane:
Supported inputs:
The beginner workflow converts marked piece/file/rank entries into
normal chess moves before the same repair grid runs. For example, a
circled knight plus f and 3 is treated as
Nf3, and a circled pawn plus e and
4 is treated as e4. If a mark is ambiguous,
the row stays editable and the legal-move suggestions help you correct
it.
To print blank scoresheets from the same pane:
120 is the default.Traditional blank scoresheets continue in 60-move pages. Beginner blank scoresheets use the full first page plus continuation pages, so a move-120 beginner scoresheet produces enough pages for long tournament games.
Via Menu: - Analysis → Toggle Analysis Pane (⌘1) - Analysis → Show Engine Console (⌘2) - Workspace menu provides direct pane toggles (including Repertoire Scan, Repertoire Builder, Training, Features, Chat, Database, and more) - Workspace → Close Active Pane (⌥⌘W) closes the last pane you clicked, excluding the locked Game pane. - Workspace → Open Active Pane in New Window (⇧⌥⌘O) detaches the last pane you clicked when a pane header button is hard to reach.
Via Toolbar: - Click pane icons in the toolbar to show/hide
Note: Specific pane shortcuts may vary. Check the application’s Workspace menu for current bindings.
Docking Areas: - Left Column: Typically the board - Right Column: Analysis, books, chat, etc. - Bottom Row: Database browser, game lists
Resizing: - Drag the splitters between panes to adjust sizes - Panes within the same dock slot share the available space
Important Layout Rule: > If no panes are docked in the bottom row or the right column, those areas should only be as high (bottom row) or as wide (right column) as the docking target.
If your layout becomes disorganized: - Look for Workspace → Reset Layout in the menu (exact location may vary) - Or close and reopen the application (layout is saved)
Panes can be detached into separate windows.
How to detach: - Click the Open in New Window icon in a pane header. - Or click inside a pane and use Workspace → Open Active Pane in New Window. - The detached pane keeps working as a live view with the same app state.
Use cases: - Keep Analysis or Repertoire Builder on a second monitor - Keep Repertoire Scan Results visible while browsing games in the main workspace
Customize the look of the board and pieces to suit your preferences.
Available Themes: - wood, slate, marble, maple, cherry - aluminium, brazilwood, cumaru, lanta, lapis - mahogony, purpleheart, sand, sandlewood, silverwood
Available Piece Sets: - Tepoztlan: Bold public-domain diagram pieces - Jiutepec: Fine-lined public-domain diagram pieces - Cuernavaca: Classic public-domain diagram pieces (default) - Sashité: Polished public-domain set - Wooden - Wooden Inlay - Lighter Wooden Inlay - Classic Wood pieces - Pale Inlay - Ebony Inlay - Light Ebony Inlay - Outlined Inlay - Outlined Wooden - Brown Wood - Cyberpunk
Styles: - shadow: Pieces with drop shadows - outline: Pieces with outlines - plain: Flat pieces without effects
The style control appears only for spritesheet-based sets. Tepoztlan, Jiutepec, Cuernavaca, Sashité, and the individually rendered wood sets use their own fixed artwork, so the style control is hidden for those sets.
The Appearance tab also lets you save and reuse collections of color settings. A color theme stores the Light and Dark palette overrides from the Appearance editor, including PGN colors, workspace colors, board colors, Repertoire Builder flowchart move tints, database row backgrounds, database table background, header text, and row text.
To save a theme:
To load a theme, choose it from Saved Themes and click Load. New installs include example themes such as Cinnamon, Lemon, Lime, Pale, Pink, Snow, and White Leather so you can start from a preset instead of creating one from scratch. To remove a saved theme, choose it and click Delete. Click Open Folder to reveal the theme files in Finder.
Theme files are stored as JSON in:
~/Documents/AIChessGM/Settings/Themes/
Theme filenames are based on the theme name, for example
Club Dark is saved as club-dark.json. The
display name is preserved inside the JSON file.
For better visibility: - Use high-contrast themes (e.g., marble with dark pieces) - Enable board coordinates - Increase piece scale
Shortcuts listed here reflect current menu bindings as of March 2026. If something differs, the app menus are the source of truth. Conflict policy: ⌥⌘A is reserved for Analyze Games… to avoid collisions.
| Command | Shortcut | Description |
|---|---|---|
| New Database… | ⌘N | Create a new chess database |
| Open… | ⌘O | Open a file (PGN, database, or book) |
| Import… | ⌘I | Import PGN games into the database |
| Save Game | ⌘S | Save the current game |
| Save Game As… | ⇧⌘S | Save the game with a new name |
| Save Game As PDF… | — | Save the current Game pane as a paginated PDF with comments and variations |
| Save Game As HTML… | — | Save the current Game pane as a self-contained HTML page with deep-link anchors |
| Export… | ⌘E | Export game or data to file |
| Email Game… | ⇧⌘E | Compose an email with the current game (PGN export + attachment) |
| Print… | ⌘P | Print the current game |
| Command | Shortcut | Description |
|---|---|---|
| Undo Move | ⌘Z | Undo the last move |
| Redo Move | ⇧⌘Z | Redo a previously undone move |
| Set Up Position… | — | Enter position setup mode |
| Command | Shortcut | Description |
|---|---|---|
| New | — | Start a new game |
| Edit Header… | — | Edit game metadata (players, event, etc.) |
| Save | — | Save the current game |
| Add to Database… | ⇧⌘D | Save the current scratch game into the active database (or MyGames if none is active) |
| Delete Moves After Current | ⇧⌘⌫ | Truncate the line after the current ply |
| Flip Board | ⌘F | Flip board orientation |
| Play vs Engine… | ⌥⌘P | Start a timed game against a configured engine |
| End Engine Game | ⌥⇧⌘P | End an active engine game |
| Play Engine vs Engine… | ⌥⌘E | Start a match between two configured engines |
| Stop Engine vs Engine | ⌥⇧⌘E | End an active engine vs engine match |
| Play on Lichess… | ⌥⌘L | Start a Lichess session |
| End Lichess Game | ⌥⇧⌘L | End a Lichess session |
| First Move | ↑ | Jump to the start of the game |
| Previous Move | ← | Go back one move |
| Next Move | → | Go forward one move |
| Last Move | ↓ | Jump to the end of the game |
| Copy Position (FEN) | ⇧⌘C | Copy the current position in FEN notation |
| Paste Position (FEN) | ⇧⌘V | Set the position from FEN in clipboard |
| Save Video… | — | Open board video export (batch or live recording) |
| Paste PGN and Add to MyGames | — | Parse PGN from clipboard and append it to MyGames |
| Command | Shortcut | Description |
|---|---|---|
| Engines Manager… | ⇧⌘, | Open the engines configuration dialog |
| Command | Shortcut | Description |
|---|---|---|
| Start Engine Analysis | ⌘A | Begin engine analysis |
| Stop Engine Analysis | ⇧⌘A | Stop engine analysis |
| Compare Pieces for Exchange… | — | Compare one White and one Black piece with equal-time paired engine searches; right-click a piece for Compare Exchange With… |
| Show Tactical Tension… | — | Mark non-king pieces with equal attacker/defender counts and show a value-aware static exchange estimate |
| Analyze Games… | ⌥⌘A | Batch-analyze games |
| Analyze Current Position Features | ⌥⇧⌘F | Compute a transient feature and motif snapshot for the board currently on screen |
| Analyze Game Features (Current Game) | — | Compute and store full-game features and motifs for the active game |
| Analyze Game Features (Background) | — | Start the same full-game feature workflow from the background menu entry |
| Analyze Features (Filtered Games)… | ⌥⌘F | Batch feature analysis for the currently filtered set |
| Analyze Features (All Games)… | — | Batch feature analysis for the entire database |
| Analyze Repertoire (Filtered Games)… | — | Batch repertoire scan on the current filtered set |
| Analyze Repertoire (All Games)… | — | Batch repertoire scan on the entire database |
| Create Analysis Puzzle Files (Filtered Games)… | — | Build local puzzle CSVs from analyzed mistakes in filtered games |
| Create Analysis Puzzle Files (All Games)… | — | Build local puzzle CSVs from analyzed mistakes in the entire database |
| Repertoire Scan Results… | — | Open the Repertoire Scan Results pane |
| Open AI Snapshots Folder | — | Open the app’s AI artifacts folder in Finder |
| Toggle Analysis Pane | ⌘1 | Show/hide the analysis pane |
| Show Engine Console | ⌘2 | Show raw engine output |
| AI: Describe Current Position | ⌥⌘D | Describe the current position |
| AI: Annotate Current Move (Append) | — | Add an AI comment for the current move (append) |
| AI: Annotate Current Move (Replace) | — | Add an AI comment for the current move (replace) |
| AI: Add Comments for Mistakes/Blunders/Inaccuracies (Current Game) | ⌥⌘T | Generate targeted AI comments for error moves |
| AI: Annotate Game (Ideas) – Append | ⌥⌘G | Add idea-focused commentary to the whole game |
| AI: Annotate Game (Ideas) – Replace | ⌥⇧⌘G | Replace existing idea-focused commentary |
| Command | Shortcut | Description |
|---|---|---|
| Find Position | — | Search for the current position in the database |
| Open Database Browser | ⌘D | Open the database game browser |
| Filter… → By Current Opening Tree… | — | Keep only games that stay inside the currently open Repertoire Builder tree for a chosen number of plies |
| Filter… → By White Rating… | — | Keep games where White’s Elo is at least the chosen value |
| Filter… → By Black Rating… | — | Keep games where Black’s Elo is at least the chosen value |
| New Database… | ⇧⌘N | Create a new database (alternate) |
| Import PGN File… | ⌘I | Import PGN games (alternate) |
| Import TWIC Files Into Split Folders… | — | Build a local GM-style database from selected TWIC PGNs, split by opening, White player, and Black player |
| Download Opponent Games… | — | Download games from Lichess or Chess.com into the selected or a new database |
| Export Database… | ⇧⌘E | Export entire database to PGN |
| Search Games… | ⇧⌘F | Search games by player, opening, etc. |
| Split Database By Opponent… | — | Create opponent-specific PGN shards from a parent PGN database |
| Split Database By Opening… | — | Create opening-specific PGN shards using the Repertoire Builder split-opening labels |
| Split Database By White Player… | — | Create one PGN per player from the White headers |
| Split Database By Black Player… | — | Create one PGN per player from the Black headers |
| Merge Split Database Into Parent… | — | Rebuild the parent PGN from opponent split files |
| Convert Database to Repertoire Builder… | — | Build an .otb tree from a database |
| Split Database by Player… | — | Generate side-specific outputs (AsWhite /
AsBlack) |
| Add Missing ECO Codes… | — | Automatically add ECO codes to games |
| Command | Shortcut | Description |
|---|---|---|
| Open Tree… | ⇧⌘O | Open an existing .otb in the Repertoire Builder
pane |
| Convert CTG Book to Repertoire Builder… | — | Convert .ctg to .otb |
| Import From Book into Repertoire Builder… | — | Merge a book into an existing .otb |
| Import TWIC Split Opening Stats… | — | Refresh stats for moves already in the loaded split tree after verifying the selected TWIC opening matches |
| Import TWIC Opponent Moves… | — | Refresh stats for a matching split opening PGN and add only opponent replies gated by existing repertoire-owner moves |
| Convert Repertoire Builder to Database… | — | Export .otb to .pgn or
.cgmdb |
Commands may appear in multiple menus by design. The intent is fast access from either a file-centric flow or a database/workspace-centric flow.
Canonical menu locations: - File: create/open/import/export at the file level - Database: search, browser, ECO, split, and database-wide workflows - Analysis: live engine analysis, batch analysis, and AI annotation actions
.otb1a,
5/7, or short letter tags.AIChessGM now uses a Documents-based root folder:
~/Documents/AIChessGMBy default, these core subfolders are auto-created:
BackupsDatabasesEngineLogsEnginesMotifsOpeningBooksPdfBooksPuzzlesSettingsVideosOpen Settings → Folders to maintain the main workspace roots in one place:
Behavior details:
~/Documents/AIChessGM..otb inside the White Repertoire folder or one of
its subfolders is treated as White-owned..otb inside the Black Repertoire folder or one of
its subfolders is treated as Black-owned.Important generated files:
~/Documents/AIChessGM/Settings/repertoire_scan_results.json~/Documents/AIChessGM/Puzzles/repertoire_puzzles_white.csv~/Documents/AIChessGM/Puzzles/repertoire_puzzles_black.csv~/Documents/AIChessGM/Puzzles/analysis_puzzles_white.csv~/Documents/AIChessGM/Puzzles/analysis_puzzles_black.csv~/Documents/AIChessGM/Puzzles/analysis_puzzles_motif_summary.csv~/Documents/AIChessGM/Puzzles/MotifTraining/analysis_puzzles_motif_<motif_slug>_white.csv~/Documents/AIChessGM/Puzzles/MotifTraining/analysis_puzzles_motif_<motif_slug>_black.csv~/Documents/AIChessGM/Puzzles/pdf_diagram_puzzles.csvsaved_positions_puzzles.csv~/Documents/AIChessGM/Puzzles/lichess_db_puzzle.csv~/Documents/AIChessGM/Videos/*.mp4Repertoire Builder split outputs:
.otb produces a sibling folder:
<YourTreeStem>-Split/.otb.-INTERSECT-...
pattern used by split resolution.Migration behavior:
~/Documents/AIChessGM.Problem: Engine doesn’t appear in Engines
Manager
Solutions: - Ensure the engine executable has execute
permissions: chmod +x /path/to/engine - Verify the engine
is UCI-compatible (most modern engines are) - Check the path is correct
(absolute path recommended) - Try running the engine in Terminal to
confirm it works
Problem: macOS blocks the engine with a security
warning
Solutions: - In Finder, Control-click the engine
executable and choose Open, then confirm
Open. - Or go to System Settings → Privacy
& Security and click Open Anyway for the
blocked app. - After allowing it once, re-add the engine in
Engines → Engines Manager… if needed.
Problem: Opening book file fails to load
Solutions: - Confirm the file format (.bin for
Polyglot, .ctg for ChessBase, .otb for Repertoire Builder) - Check file
permissions (must be readable) - For CTG books, ensure all related files
are present (.ctg, .cto, .cyi) - Try a different book to rule out file
corruption
Problem: Application is slow or unresponsive
Solutions: - Close unnecessary panes - Stop engine
analysis if running - Reduce engine threads/hash if analysis is slow -
Check database size (very large databases may be slower) - Restart the
application
Problem: PGN import doesn’t complete
Solutions: - Check PGN file validity (some malformed
PGNs cause issues) - Try importing in smaller batches - Ensure
sufficient disk space - Check Console logs for error messages
Problem: Export creates a short, silent, or blank video
Solutions: - Confirm a game is loaded, or a
real-time recording session has active frames. - Ensure the narration
source is available if narration is enabled. - Try a lower FPS and
shorter export duration. - Close/disable intensive panes and retry if
the app was under heavy load. - Use Preview Voice to
confirm the selected narration voice is valid and audible. - If using
ElevenLabs or Voice.ai, confirm the API key is configured in
Settings → Voice and that a default or export-specific
cloud voice is selected. - If export appears paused, switch to
720x720, disable narration, and retry to isolate rendering
vs audio issues. - Check Console logs for BoardVideoExport
messages.
Problem: Shortcuts are unresponsive
Solutions: - Check for conflicts with system or other
app shortcuts (System Preferences → Keyboard → Shortcuts) - Ensure
AIChessGM is the active application - Try the menu command directly to
confirm the feature works - Restart the application
Problem: Chat assistant fails to respond
Solutions: - Verify API key is correct (Settings → AI →
Test Connection) - Check internet connectivity - Ensure OpenAI service
is operational (status.openai.com) - Review API usage/quotas on OpenAI
dashboard - Try a lighter or alternate model if requests time out or
fail, then retry your preferred model.
Problem: Panes are misaligned or missing
Solutions: - Reset layout via Workspace menu - Close
and reopen the application (layout is persisted) - Manually resize panes
by dragging splitters - Check that panes aren’t hidden (toggle
visibility via toolbar/menu)
Problem: Swift build fails
Solutions: - Ensure Xcode Command Line Tools are
installed: xcode-select --install - Verify Swift version:
swift --version (should be Swift 6) - Clean build:
swift package clean && swift build - Check for
missing dependencies in Package.swift - Ensure macOS 14+ SDK is
available
Screenshots illustrate key workflows and concepts throughout this documentation.
docs/flip-board.png - Board orientation toggle (White ↔︎
Black)
docs/board-coordinates.png - File/rank labels (a-h, 1-8)
shown on squares
docs/copy-position.png - Copy current position to
clipboard (FEN) docs/paste-position.png - Paste position
from clipboard into board
docs/analysis-pane.png - Engine evaluation display with
best move arrows
docs/best-move-arrows.png - Arrows showing
engine-recommended moves on board
docs/multi-pv-lines.png - Multiple principal variation
lines displayed in analysis
docs/loading-book.png - Opening book file selection
dialog
docs/book-statistics.png - CTG/Polyglot book showing
game counts, percentages
docs/ctg-filters.png - CTG book filter controls (game
percentage, score percentage, minimum games)
docs/agent-selection.png - Training pane dropdown for
choosing training agent
docs/training-controls.png - Start training, hints,
progress tracking
docs/hint-feedback.png - Visual feedback when requesting
hints during training
docs/setup-mode.png - Drag pieces to set custom
position, Done button
docs/castling-ui.png - Castling rights selector (O-O,
O-O-O)
docs/fen-operations.png - Copy FEN, Paste FEN from
clipboard
docs/keyboard-shortcuts.png - Common keyboard shortcuts
for navigation
docs/engine-settings.png - Engine manager interface
showing configured engines
Note: macOS screenshot shortcuts are ⌘⇧3 (full screen), ⌘⇧4 (selection), and ⌘⇧5 (capture/record toolbar).
AIChessGM is built with Swift 6 and SwiftUI, designed specifically for macOS 14+. It leverages modern Apple technologies for performance and native integration.
Created by James Coons — contact:
support@aichessgm.com.
Project Structure: - Swift Package Manager for build system - UCI protocol for engine communication - SQLite for database storage - SwiftUI for user interface
For developer documentation, see: - README.md: Build and
development instructions - FEATURES.md: Complete feature
list and implementation status - Training.md: Training
system architecture - Docs/AddingNewPanes.md: Guide for
extending the workspace
Enjoy using AIChessGM to improve your chess! If you have feedback or encounter issues, please consult the troubleshooting section or refer to the developer documentation.