Version: 0.2.72
Last Updated: March 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.
.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) Add opening books (optional) - Load
.bin, .ctg, or .otb files when
you want book-assisted play and opening prep.
Note: AIChessGM requires at least one database to be active. MyGames is a good default if you’re unsure.
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.
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
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
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 Opening Books section:
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.
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])NSSpeechSynthesizer voice and click Preview
Voice to audition before export.AIChessGM uses
NSSpeechSynthesizerfor reliable file-based text-to-speech on macOS.
Use Settings → Video to control defaults used by Game → Save Video…:
720, 1080,
1440)MP4 (.mp4) and
MOV (.mov)AIChessGM can compute and store position features, move features, and higher-level motifs (recognizable strategic/tactical patterns) for a game. These are visualized in the Features Pane, and the selected motif can be explored in depth in the Motif Pane.
Feature analysis is separate from standard engine analysis. It’s designed to produce durable annotations you can browse later.
For a game that has feature data, the Features pane typically includes:
If you select a motif in the Features pane, AIChessGM stores the selection and the Motif Pane shows rich details for that motif.
The Motif pane can show:
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.chessgm.app/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:
Important 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 (Polyglot), .ctg
(ChessBase), or .otb (Repertoire Builder) fileAIChessGM also supports side-specific books via the Opening Book — White and Opening Book — Black panes. This is useful for keeping separate repertoires for each color.
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
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.
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:
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:
.otb and
auto-loads it when the pane opens (unless a rule requests a different
tree).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
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
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.
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 workflow to convert printed-book diagrams into trainable local puzzles:
W?
/ B? and nearby move notation), then review legality
checks.Optional puzzle options:
Output:
~/Documents/AIChessGM/Puzzles/pdf_diagram_puzzles.csvAIChessGM includes optional AI features for explanations, annotations, and automation.
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).
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.
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.
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:
This lets you go from scanned diagram to local training puzzle without manual CSV editing.
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)
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. - 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: - merida: Classic tournament style - berlin: Modern clean design - leipzig: Traditional figurine style - alpha: Minimalist style
Styles: - shadow: Pieces with drop shadows - outline: Pieces with outlines - plain: Flat pieces without effects
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 |
| 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 |
| Analyze Games… | ⌥⌘A | Batch-analyze games |
| Analyze Position Features (Current Game) | ⌥⇧⌘F | Compute features and motifs for the current game |
| 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 |
| New Database… | ⇧⌘N | Create a new database (alternate) |
| Import PGN File… | ⌘I | Import PGN games (alternate) |
| Export Database… | ⇧⌘E | Export entire database to PGN |
| Search Games… | ⇧⌘F | Search games by player, opening, etc. |
| 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… | — | 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 |
| 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
.otbAIChessGM now uses a Documents-based root folder:
~/Documents/AIChessGMCore subfolders are auto-created:
BackupsDatabasesEngineLogsEnginesOpeningBooksPdfBooksPuzzlesSettingsVideosImportant 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.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 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:
james@coons.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.