CARA

1.1 What is CARA?

CARA (Chess Analysis and Review Application) is a full-featured desktop application designed for analyzing and reviewing chess games. Unlike chess playing applications or puzzle solvers, CARA focuses exclusively on post-game analysis and review, helping you understand your games, identify mistakes, recognize patterns, and improve your chess understanding.

The development of CARA was motivated by the author's underwhelming experience with existing (and sometimes quite expensive) chess analysis tools, which often fell short in terms of usability, practical workflow integration, and the ability to deliver meaningful, actionable insights. Many applications overwhelmed users with unnecessary complexity and provided superficial analysis that didn't translate into genuine improvement. CARA was created to bridge this gap, offering an intuitive interface that makes deep game analysis accessible in an efficient manner while providing the detailed insights needed to understand not just what moves were played, but why they were played and how to improve.

Whether you're analyzing your own games, studying master games, or reviewing games from online platforms like Lichess or Chess.com, CARA provides the tools you need to gain deep insights into chess positions, moves, and patterns.

1.2 Key Features

CARA offers an extensive set of features designed to support thorough chess game analysis and review. Here are the main capabilities:

• PGN Database Management: Complete management of chess game collections stored in PGN format. The system supports opening multiple PGN databases simultaneously, each displayed in its own tab for easy navigation. Powerful search functionality allows you to find games by player names, dates, openings, results, and other criteria. Built-in deduplication helps identify and remove duplicate games across databases. Bulk Operations allow you to efficiently perform repeatable database maintenance tasks. Import games from local PGN files or directly from online platforms like Lichess and Chess.com, with support for filtering by date range, game type, and other criteria.
• Interactive Chessboard: Beautiful, feature-rich chessboard at the heart of the application, providing an intuitive visual interface for game review and analysis. The board integrates seamlessly with game analysis and manual analysis through extensive visual indicators. Played move arrows highlight the last move made in the game, while best alternative move arrows indicate superior moves found during analysis. During manual analysis, PV1, PV2, and PV3 arrows display the principal variations from MultiPV analysis, allowing you to explore multiple candidate moves simultaneously. All arrows can be individually shown or hidden to customize the display according to your analysis needs. The board features a positional heatmap overlay that visualizes positional factors like weak squares, passed pawns, outposts, piece activity, and king safety through color-coded gradients. Additional toggleable elements include coordinate labels, turn indicator, game information panel, evaluation bar, and material widget. All visual elements are fully customizable through the configuration system.
• Game Analysis: Automatic analysis of chess games using UCI-compatible chess engines, with move assessment through MultiPV (Multiple Principal Variations) analysis and before-and-after position evaluation. The system analyzes each move by comparing the position before and after the move, evaluating multiple candidate moves simultaneously, and calculating Centipawn Loss (CPL) to classify moves as Good, Inaccuracy, Mistake, Blunder, or Brilliant. An optional brilliancy detection step can use a separate engine from the main game analysis, so you can for example use a fast engine for the main analysis and another for brilliancy detection. This approach provides detailed evaluation metrics and move quality assessments. Supports both single game analysis and bulk analysis of entire databases.
• Game Summary: Complete game overview combining statistical analysis, key moments, and visual insights. The summary provides per-player statistics (accuracy, average CPL, move counts by classification), phase-by-phase performance breakdowns (Opening, Middlegame, Endgame), identification of top best and worst moves for each player, evaluation graph data, and automatically detected game highlights. The summary synthesizes all analysis data into a cohesive overview that helps you quickly understand the flow of the game, identify critical moments, and assess each player's performance across different phases of play.
• Game Highlights: Automatic detection of 44 tactical and positional patterns through an extensible rule-based system. The system includes rules for detecting pins, forks, skewers, batteries, discovered attacks, tactical sequences, positional improvements, evaluation swings, material imbalances, and many more patterns. Highlights are organized by game phase and help you quickly identify key moments. The rule-based architecture is designed for extensibility: new highlight detection rules can be easily added by implementing a simple rule interface, allowing the system to grow and adapt to detect additional patterns and tactical themes.
• Moves List: Centralized table view that encapsulates all important per-move information in one place. The moves list displays move notation, evaluations, move classifications, best move alternatives, Centipawn Loss (CPL) values, engine depth, material counts, FEN positions, and more across 32 available columns. The system features a flexible column profile management system, allowing you to create, save, and switch between different view profiles. Each profile can customize which columns are visible, their display order, and column widths, enabling you to tailor the view to your specific analysis needs—whether focusing on opening transitions, move assessment, or material tracking.
• Player Statistics: A dedicated Player Stats tab aggregates results across many analyzed games for one player at a time: overview figures, an optional activity heatmap (when you played), accuracy and move-quality charts, date-based progression charts, openings and endgame summaries, best and worst games, significant moves, and automatic error-pattern hints. You can show or hide each section to tailor the page. See section 5.7 for a full walkthrough.
• Manual Analysis: Perform continuous engine analysis on any position with MultiPV support. You can navigate through game positions while maintaining continuous analysis of the current position. Hovering over principal variation moves displays a beautiful optional miniature board showing the resulting position. You can freeze the displayed PV lines while the engine keeps searching, and—when the assigned engine reports UCI W/D/L—optionally show a win/draw/loss probability bar for the best line. Positional plan exploration extracts piece trajectories from PV lines, visualizing how pieces move through the engine's recommended plan on the chessboard. You can explore positional plans for up to three PV lines (PV1, PV2, PV3) independently, with configurable options for the number of pieces to track and exploration depth.
• Opening Explorer: Browse the opening path that led to the current position and expand book continuations from here using CARA's ECO opening database. Embedded mini boards follow the main board's piece set, colors, and orientation. Jump to a position on the path or open the corresponding Lichess opening explorer page. When an encyclopedia article is available, an information control next to the opening name opens a richer description of that opening (see section 4.5.4.1). Access via View → Opening Explorer (F4).
• Annotations: Powerful free-form annotation system for marking positions, ideas, and analysis insights. Unlike other chess applications, text can be freely positioned anywhere on the board, adjusted in size and rotated. In addition to text, you can add arrows, circles, and square highlighting with customizable colors. Annotations are position-specific, attached to the current path in the game tree (mainline or variation), and are compressed and serialized in a PGN metadata tag to keep the PGN move notation clean. This flexible annotation system enables you to create rich, personalized study materials and analysis notes.
• UCI Engine Integration: CARA uses the UCI (Universal Chess Interface) protocol, so you can use any UCI-compatible chess engine (for example Stockfish, Lc0, Komodo, Shredder). The system supports multiple engine setups with per-task configuration, allowing you to assign different engines to different analysis tasks: evaluation (for the evaluation bar), game analysis, manual analysis, and brilliancy detection. Each task can have its own engine and task-specific parameters such as thread count, depth limits, time limits, and engine-specific options. You can use a single engine for all tasks or mix and match—for example, a fast engine for evaluation and a stronger one for deep game analysis. Each engine operation runs in dedicated threads, keeping the interface responsive. If you’re not sure what to install, see section 7.10 “Recommended Chess Engines”.
• AI Summary: Interactive chat interface allowing you to discuss any position in a game with a Large Language Model (LLM). The AI model has access to extensive game data, including detailed engine analysis, move classifications, evaluation metrics, and positional information, enabling it to provide accurate assessments of the game, played moves, and current position.
• Notes: Plain-text notes for the current game, stored in a PGN metadata tag (CARANotes). You can write free-form comments, plans, or analysis; move notation in the text is automatically linked so you can click a move to jump to that position. Notes also support a small Markdown subset (headings, bold/italic, inline code, strikethrough, and blockquotes) via the formatting toolbar. Notes are saved in memory and persisted when you save the database.

These features work together to provide a complete analysis environment, from importing and organizing games to deep positional understanding and statistical insights.

1.3 Technical details

CARA was built in large part by an AI model under the author's direction. The author took special care to ensure the AI adhered to the established architectural guidelines and coding conventions throughout the development process, while proposing the features, user stories, and UX design. This project served as an experiment to explore the feasibility of building a full-fledged, complex desktop application with Python using AI code completion, testing whether modern AI tools can produce polished, fully-featured software when guided by clear architectural principles and consistent oversight.

CARA is built with PyQt6 and follows PyQt's Model/View architecture with additional separation of business logic using Controllers and signal observation patterns, ensuring a responsive user interface and clean separation of concerns. Views observe models through Qt's signal/slot mechanism, automatically updating when model data changes, while Controllers orchestrate business logic and coordinate between services and models. Following a strict coding convention, all UI styling, including fonts, colors, sizes, and dimensions, is defined in a centralized configuration file with no hardcoded values in the view components. This allows for complete customization of the application's appearance without modifying code.

1.4 About This Manual

This manual provides comprehensive documentation for CARA, covering everything from installation and basic usage to advanced configuration and troubleshooting. The manual is organized into seven main sections:

• Introduction: Overview of CARA, its features, and what makes it unique
• Attributions: Credits for libraries, resources, and licensing information
• Installation: Step-by-step installation instructions for Windows, macOS, and Linux
• Getting Started: Interface overview and your first game analysis
• Common Tasks: Detailed guides for everyday operations
• Complete Reference: Comprehensive menu and keyboard shortcut documentation
• Advanced Topics: Configuration files, troubleshooting, and performance optimization

Navigation: Use the Table of Contents at the top to quickly jump to any section. All section headings are clickable links that navigate directly to that content. Cross-references throughout the manual link to related sections for easy navigation.

2.1 Libraries and Dependencies

CARA relies on the following open-source libraries:

• PyQt6 (>= 6.6.0) — licensed under GNU GPL v3.0.
• python-chess (>= 1.999) — licensed under GNU GPL v3.0.
• requests (>= 2.31.0) — licensed under the Apache License 2.0.
• asteval (>= 0.9.31) — licensed under the MIT License.
• charset-normalizer (>= 3.0.0) — licensed under the MIT License.

The author would like to express sincere appreciation to the developers and maintainers of these open-source projects. Their dedication and excellent work have made this application possible, and their contributions to the open-source community are invaluable.

2.2 Chess Pieces

The default chess pieces CARA ships with are the classic SVG set created by User:Cburnett and hosted on Wikimedia Commons. These pieces are distributed under the dual licenses Creative Commons Attribution-ShareAlike 3.0 and GNU Free Documentation License, which permit reuse and modification as long as attribution is provided and derivative works remain under the same license terms. Full details and download links for every piece in the set are available in the SVG chess pieces collection on Wikimedia Commons.

CARA also ships with the Kosal Chess Piece Set by philatype, licensed under Creative Commons Attribution 4.0 International (CC BY 4.0), which permits reuse and modification as long as attribution is provided.

We extend our thanks to Cburnett, the Wikimedia Commons community, and philatype for maintaining these high-quality, freely reusable chess assets.

2.3 Opening Books and ECO Database

CARA uses two types of opening resources for identifying book moves and classifying chess openings:

ECO Database: The application includes an ECO (Encyclopaedia of Chess Openings) database based on the eco.json project by hayatbiralem, licensed under the MIT License. This extensive database contains over 12,000 known opening variations and is a collation of multiple chess opening sources including lichess, SCID database, Wikipedia, ChessTempo, and other public chess databases. The original eco.json data was compiled by Ömür Yanıkoğlu, with credit to Shane Hudson for the original SCID opening data. The database files (eco_base.json and eco_interpolated.json) were merged from the original source files (ecoA.json, ecoB.json, ecoC.json, ecoD.json, ecoE.json) that were organized by ECO code starting letter, simplifying lookup operations while maintaining complete coverage of chess opening theory.

Polyglot Opening Books: CARA supports Polyglot-format opening books, a binary format originally developed by Fabien Letouzey. The application includes a collection of Polyglot opening books organized by opening type (all openings, closed, flank, Indian, open, semi-closed, and semi-open). These books were compiled from publicly available sources and converted to the Polyglot format. For more information about the Polyglot format and tools, see the Polyglot repository maintained by sshivaji (a fork of Fabien Letouzey's original work).

Both resources work together to provide complete opening identification: the ECO database offers position-based classification with standardized codes and names, while the Polyglot books provide move-based detection of book moves during game analysis.

The author would like to express sincere appreciation to the creators and maintainers of these opening resources.

2.4 CARA License

CARA (Chess Analysis and Review Application) is released under the GNU General Public License version 3 (GPL-3.0).

2.4.1 What This Means for You

The GPL-3.0 license grants you the following freedoms:

• Freedom to use: You can use CARA for any purpose, including commercial use (e.g., chess trainers can use it with their students)
• Freedom to study: You have access to the source code to understand how CARA works
• Freedom to modify: You can modify CARA to suit your needs
• Freedom to distribute: You can share CARA with others

2.4.2 License Requirements

When distributing CARA (whether modified or unmodified), you must:

• Provide attribution: Include the original copyright notice and license
• Include source code: Make the complete source code available to recipients
• Use the same license: Any modified versions or derivative works must also be licensed under GPL-3.0
• Preserve notices: Keep all copyright and license notices intact

2.4.3 Why GPL-3.0?

GPL-3.0 was chosen for CARA because:

• Dependency compatibility: CARA uses GPL-3.0 licensed dependencies (PyQt6, python-chess), requiring GPL-3.0 compatibility
• Prevents proprietary resale: The copyleft provision ensures that CARA and any derivative works remain free and open source, preventing proprietary resale or rental
• Allows commercial use: You can use CARA commercially (e.g., in training, coaching, or analysis services) as long as you comply with the license terms
• Protects user freedoms: Ensures that users always have access to source code and can modify the software

2.4.4 Important Notes

• No warranty: CARA is provided "as is" without any warranty. See the full license text for details.
• Derivative works: If you create a modified version of CARA, it must also be licensed under GPL-3.0 and you must make the source code available. This prevents proprietary forks while still allowing open-source improvements.
• Commercial services: You can offer commercial services using CARA (e.g., chess coaching, analysis services) without restrictions, as long as you comply with the license terms when distributing the software itself.

For the complete license text, see the LICENSE file in the CARA distribution or visit gnu.org/licenses/gpl-3.0.html.

2.5 Special Mentions

Special thanks to the members of the HIARCS chess forum for their help in testing and refining the application.

• Tibono2: For his work on the ELO estimation formulas, the brilliancy detection system, testing and identifying bugs.
• Leto: For his feature suggestions and also testing and identifying bugs.

3.1 System Requirements

Before installing CARA, ensure your system meets the following requirements:

Operating System

The application has been tested on Windows 11, macOS Tahoe 26.2, and Linux Ubuntu, Debian (Gnome) and Fedora (KDE Plasma). Linux app bundles are provided for x86_64 (amd64) and aarch64 (arm64).

Python

Python 3.8 or higher is required. CARA uses PyQt6, which requires Python 3.8+. See section 3.2 for installation instructions.

Screen Resolution

A minimum screen resolution of 1280×1024 pixels is recommended. Some dialogs require at least 800 pixels in width and 900 pixels in height to display properly. Lower resolutions may cause dialogs to be cut off or difficult to use.

Hardware

No specific hardware requirements beyond what is needed to run Python and the operating system. For optimal performance when analyzing games with chess engines, a modern multi-core processor is recommended.

3.2 Installing Python

CARA requires Python 3.8 or higher. If you don't have Python installed, you can install it using the methods below:

Windows

Method 1: Using Windows Package Manager (Recommended)
Open PowerShell or Windows Terminal and run:

winget install Python.Python.3

This automatically installs Python and adds it to your PATH.

Method 2: Manual Download

1. Visit python.org/downloads and download the latest Python 3.x installer for Windows.
2. When installing, make sure to check the box labeled "Add Python to PATH" at the bottom of the installer window.

macOS

Method 1: Using Homebrew (Recommended)
If you have Homebrew installed, open Terminal and run:

brew install python3

Method 2: Manual Download

1. Visit python.org/downloads and download the latest Python 3.x installer for macOS.
2. Run the installer and follow the installation wizard.

Verifying Installation

After installation, open a terminal (PowerShell/Command Prompt on Windows, Terminal on macOS) and run:

python --version

This should display the Python version number (e.g., "Python 3.11.5").

Note: On macOS, you may need to use python3 instead of python to access Python 3.

Windows PATH Troubleshooting: If you see a "python is not recognized" error on Windows, Python may not be in your system PATH. Re-run the installer and ensure "Add Python to PATH" is checked, or manually add Python to your system PATH:

1. Find your Python installation directory (typically C:\Users\YourUsername\AppData\Local\Programs\Python\Python3XX or C:\Python3XX).
2. Press Win+X and select "System", then click "Advanced system settings".
3. Click "Environment Variables".
4. Under "System variables" (or "User variables"), select "Path" and click "Edit".
5. Click "New" and add the Python installation directory path, then click "New" again and add the Scripts subdirectory (e.g., C:\Python3XX\Scripts).
6. Click "OK" on all dialogs, then close and reopen your terminal for changes to take effect.

3.3 Installing Required Libraries

CARA requires several Python libraries to function (see section 2.1 for a complete list). These can be installed all at once using the provided requirements file.

1. Navigate to the CARA directory:
   Open a terminal (PowerShell or Command Prompt on Windows, Terminal on macOS) and navigate to the directory where you extracted or cloned CARA:
   cd path/to/cara
   Replace path/to/cara with the actual path to your CARA installation directory.
2. Install the required libraries:
   Run the following command to install all dependencies:
   pip install -r requirements.txt
   
3. Verify installation:
   After installation completes, verify that the libraries were installed correctly:
   pip list
   You should see PyQt6, python-chess, requests, asteval, and charset-normalizer in the list of installed packages.

3.4 Installation Troubleshooting

Installing pip

If pip is not available after installing Python, you can install it manually:

1. Download get-pip.py:
   Download the get-pip.py script from bootstrap.pypa.io/get-pip.py and save it to a folder on your computer.
2. Run the installer:
   Open a terminal, navigate to the folder containing get-pip.py, and run:
   python get-pip.py
   Note: On macOS, you may need to use python3 instead of python.
3. Verify installation:
   After installation completes, verify pip is installed:
   pip --version
   

Installing Dependencies Manually

If you prefer to install dependencies individually instead of using the requirements file, you can install each library separately:

1. Install PyQt6:
   pip install PyQt6>=6.6.0
   
2. Install python-chess:
   pip install python-chess>=1.999
   
3. Install requests:
   pip install requests>=2.31.0
   
4. Install asteval:
   pip install asteval>=0.9.31
   
5. Install charset-normalizer:
   pip install charset-normalizer>=3.0.0
   

After installing all dependencies, verify they are installed correctly using pip list.

3.5 Running the Application

App bundles: Download the bundle for your platform, extract it, and start CARA from the extracted folder.

To start CARA, open a terminal (PowerShell or Command Prompt on Windows, Terminal on macOS), navigate to the CARA directory, and run:

python cara.py

Note: On macOS, you may need to use python3 instead of python.

Configuration Files

CARA uses three configuration files to manage settings and preferences:

• config.json: Contains application-wide behavioral defaults such as import/export options, formulas, logging, analysis thresholds, and other non-user settings. This file is located in the app/config/ directory.
• Theme / style config files: Files such as style_default.config.json and style_light.config.json define colors, fonts, spacing, borders, and other visual styling. These files are also located in app/config/ and can be used to customize or create themes.
• user_settings.json: Stores your personal preferences and settings, including moves list column profiles, board visibility settings, PGN display options, engine configurations, keyboard shortcut overrides, and other user-specific settings. The file is automatically created when you first save settings and persists your preferences between application sessions.
• engine_parameters.json: Stores engine-specific parameters and options for each configured chess engine. Engine settings are automatically saved to this file when you configure engines through the application interface.

Where Configuration Files Are Stored

The file location for user_settings.json and engine_parameters.json is determined by CARA's configuration settings. By default, these files are stored in the CARA root directory.

However, when running CARA as an app bundle, the files are stored in different locations:

• Windows: Files are stored in the app directory (where CARA.exe is located) if the directory has write access (portable mode). If the app directory cannot be written to, files are stored in your user data directory: %APPDATA%\CARA\ (usually C:\Users\YourUsername\AppData\Roaming\CARA\).
• macOS: Files are stored in ~/Library/Application Support/CARA/.
• Linux: Files are stored in the app directory if it is writable (portable mode). Otherwise, CARA uses $XDG_DATA_HOME/CARA/ (if set) or ~/.local/share/CARA/.

4.1 Application Overview

CARA provides an integrated environment for analyzing and reviewing chess games. The application window is organized into three main panels that work together to give you complete insight into your games: the Main Panel displays the chessboard and game information, the Detail Panel provides detailed analysis views and tools, and the Database Panel manages your game collections.

The interface is designed to be intuitive and efficient. You can resize panels by dragging the splitter handles between them, customize which information is displayed, and use keyboard shortcuts for quick navigation. The application automatically updates all views when you navigate through a game, ensuring that the chessboard, move lists, evaluations, and statistics stay synchronized.

CARA separates behavioral configuration from visual styling. Use config.json for things like import/export behavior, logging, and formulas. Use the theme / style config files in app/config/ for colors, fonts, spacing, and other UI appearance settings.

All functions and features in CARA can be accessed through the menu bar at the top of the application window. Most menu items have keyboard shortcuts displayed next to them for quick access. Visual themes can be switched directly in the application through View → Theme.

4.2 The Three-Panel Layout

CARA's main window is organized into three resizable panels:

• Main Panel (left): Displays the chessboard along with game information, evaluation bar, material widget, turn indicator, and other board-related widgets. This is the primary visual interface for reviewing games and positions.
• Detail Panel (right): Contains the PGN notation pane at the top, displaying the game's move notation, and tabbed views below for detailed analysis, including the Moves List, PGN header tags, Manual Analysis, Opening Explorer, Game Summary, Player Stats, Annotations, AI Summary, and Notes. This panel provides in-depth information and analysis tools.
• Database Panel (bottom): Manages your game collections with tabs for multiple PGN databases, searchable game tables, and column customization. This panel can be collapsed to maximize space for the main and detail panels.

You can resize any panel by dragging the splitter handles between them. The database panel can be collapsed by double-clicking its splitter handle or using View → Hide Database Panel (Ctrl+Shift+D / ⌘+Shift+D). The active visual theme can also be changed from View → Theme. The status bar at the bottom of the window displays status messages and progress indicators during long-running operations.

4.3 Main Panel Components

The Main Panel displays the chessboard along with game information and analysis widgets. The board updates automatically as you navigate through moves using the arrow keys.

4.3.1 Chessboard

The chessboard displays the current position.

Rotate the board 180 degrees using the X key or Board → Rotate Board. Rotation is visual only and does not change the position—FEN notation always represents positions from White's perspective.

When you are viewing a variation (sideline) position with variation navigation enabled, the board uses a distinct theme appearance—typically a different frame color, square colors, and last-move highlight—so it is clear you are off the main line. These colors are defined in the theme / style config files under ui.panels.main.board.variation_appearance (see section 7.1.4).

Context menu: You can also right-click on the chessboard to open a context menu with quick access to common actions. These entries mirror the corresponding options from the menu bar.

The following visual indicators can be toggled on or off:

• Coordinates: File and rank labels around the board edges. Toggle with Alt+C / ⌥+C or Board → Show Coordinates.
• Turn Indicator: Shows whose turn it is to move. Toggle with Alt+T / ⌥+T or Board → Show Turn Indicator.
• Castling Rights: Shows castling availability for both sides (KQkq) as you navigate through the game. Toggle with Alt+R / ⌥+R or Board → Show Castling Rights.
• Played Move Arrow: Highlights the last move made in the game. Toggle with Alt+P / ⌥+P or Board → Show Played Move.
• Best Next Move Arrow (PV1): Shows the engine's recommended move during manual analysis mode. Toggle with Alt+B / ⌥+B or Board → Show Best Next Move.
• PV2 and PV3 Arrows: Display alternative candidate moves from MultiPV analysis during manual analysis mode. Toggle with Alt+2 / ⌥+2, Alt+3 / ⌥+3 or Board → Show Next Best Move (PV2/PV3).
• Best Alternative Move Arrow: Highlights superior moves found after analyzing the game with the Game Analysis function. The arrow appears once analysis has been performed and indicates when the played move was not optimal. Toggle with Alt+A / ⌥+A or Board → Show Best Alternative Move.
• Move Classification Icons: Small badges on the played move's destination square showing the move assessment (e.g. book move, best move, good move, brilliant, inaccuracy, mistake, miss, blunder). Available once the game has been analyzed. Toggle with Alt+4 / ⌥+4 or Board → Show Move Classification Icons.
• Game Tags: Shows or hides the Game Tags widget next to the chessboard. Toggle with Board → Show Game Tags.
• Positional Heatmap: Color-coded overlay showing positional factors (weak squares, passed pawns, outposts, piece activity, king safety). Toggle with Alt+H / ⌥+H or Board → Show Positional Heat-map.

4.3.2 Game Information Display

The game information header at the top of the Main Panel shows:

• Player names and ELO ratings from the game PGN metatags
• Game result (1-0, 0-1, 1/2-1/2, or * for indecisive results)
• Opening ECO code and name (e.g., "A00 - Unknown Opening")

When an Opening Encyclopedia article matches the displayed opening, a small ⓘ symbol appears next to the opening name. Click it to open the article. See section 4.5.4.1 for details.

Toggle visibility with Alt+I / ⌥+I or Board → Show Game Info.

4.3.3 Evaluation Bar

The evaluation bar appears on the left side of the chessboard and shows the engine's evaluation of the current position. The bar uses white and black colors: positive values (White advantage) are shown in white extending upward from the center, negative values (Black advantage) are shown in black extending downward from the center. The scale ranges from -1000 to +1000 centipawns, with division marks at 100, 200, 300, 500, and 1000 centipawns to help gauge the evaluation magnitude. Toggle with Alt+E / ⌥+E or Board → Show Evaluation Bar. When the evaluation bar is shown, the status bar displays detailed engine information including the engine name, search depth, evaluation score, principal variation, and performance metrics such as nodes per second and hash table usage. The bar always evaluates the position currently shown on the board—including variation (sideline) positions when you navigate into them.

Note: The evaluation bar requires a chess engine to be assigned to the evaluation task. See section 5.1 for instructions on configuring engines.

4.3.4 Material Widget

The material widget appears in the upper right corner of the chessboard and shows captured pieces and the material difference between the two sides. The widget updates automatically as you navigate through the game. Toggle with Alt+U / ⌥+U or Board → Show Material.

The widget is divided into three distinct sections, reading from top to bottom:

• Top section (White's captures): Displays pieces that White has captured from Black. The piece letters (P, N, B, R, Q) are always visible in light/white text color. Each letter is followed by a colon and a number indicating how many of that piece type have been captured. For example, "R:1" means White has captured one rook from Black, while "R:" (with no number after the colon) means no rooks have been captured yet.
• Middle section (Black's captures): Displays pieces that Black has captured from White, using the same notation format as the top section. The piece letters are shown in dark/gray text color to distinguish them from White's captures. For example, if you see "Q:1" in this section, it means Black has captured one queen from White.
• Bottom section (Material difference): Shows the material balance using the delta symbol (Δ) followed by a value in pawns. The notation appears as "Δ: ±X.X" where the value represents the material advantage. Positive values (e.g., "Δ: +2.0") indicate White has a material advantage, while negative values (e.g., "Δ: -1.0") indicate Black has the advantage. The calculation uses standard piece values: Pawn = 1.0, Knight/Bishop = 3.0 each, Rook = 5.0, and Queen = 9.0. This gives you a quick visual reference to see who's ahead in material at any point in the game.

Pieces are displayed using standard chess notation letters: P for Pawn, N for Knight, B for Bishop, R for Rook, and Q for Queen.

4.3.5 Castling Rights Widget

The castling-rights widget shows which castling options are still available in the current position (KQ for White, kq for Black). It updates automatically as you navigate through the game.

Toggle visibility with Alt+R / ⌥+R or Board → Show Castling Rights.

4.3.6 Game Tags Widget

The Game Tags widget is shown next to the chessboard and displays the tags assigned to the active game.

To show or hide the widget, use Board → Show Game Tags (see section 6.3).

4.3.7 Turn Indicator

The turn indicator shows which side is to move in the current position. Toggle with Alt+T / ⌥+T or Board → Show Turn Indicator.

4.3.8 Positional Heatmap

The positional heatmap is a color-coded overlay that visualizes positional factors for each piece on the chessboard. It helps you quickly identify positional strengths and weaknesses by displaying colored gradients on squares containing pieces.
Toggle with Alt+H / ⌥+H or Board → Show Positional Heat-map.

The heatmap evaluates nine positional factors:

• Passed Pawns: Pawns with no enemy pawns in front of them on the same or adjacent files. These are generally advantageous and shown in green.
• Backward Pawns: Pawns behind friendly pawns that cannot advance safely. These are positional weaknesses shown in red.
• Isolated Pawns: Pawns with no friendly pawns on adjacent files. These are vulnerable and shown in red.
• Doubled Pawns: Multiple pawns on the same file. These reduce pawn mobility and are shown in red.
• King Safety: Evaluates king safety based on open files, pawn shield, and exposure. Unsafe kings are shown in red, well-protected kings in green.
• Weak Squares: Squares that cannot be defended by pawns. Pieces on weak squares are shown in red.
• Piece Activity: Evaluates piece mobility and central control. Active pieces with good mobility are shown in green, inactive pieces in red.
• Undeveloped Pieces: Pieces still on starting squares and blocked. These are shown in red.
• Outpost Squares: Squares protected by friendly pawns that cannot be attacked by enemy pawns. Pieces on outpost squares (especially knights) are shown in green.

Color Coding: The heatmap uses color gradients to represent positional scores:

• Green: Positive positional factors (strong positions, active pieces, passed pawns, outposts)
• Red: Negative positional factors (weak squares, inactive pieces, pawn weaknesses, exposed kings)
• Yellow: Neutral positions (scores near zero)

The intensity of the color indicates the strength of the positional factor—darker colors represent stronger effects. The heatmap only displays on squares that contain pieces, and each piece is evaluated from its own color's perspective.

Tooltip Information: Hovering your mouse over any piece displays a detailed tooltip showing:

• The piece's overall positional assessment
• Specific positional factors affecting the piece (with checkmarks for positive factors and warning symbols for negative factors)
• Position status (whether the piece is under attack, defended, or both)
• The combined evaluation score and breakdown by rule

This detailed information helps you understand why a piece is evaluated as strong or weak and which specific positional factors contribute to the assessment.

4.4 Database Panel

The Database Panel, located at the bottom of the application window, manages your chess game collections. It displays all open PGN databases in a tabbed interface, allowing you to work with multiple game collections simultaneously. Each database appears in its own tab, and you can switch between them by clicking the tab labels.

4.4.1 Database Tabs

The panel uses tabs to organize multiple databases:

• Clipboard Tab: Always appears first and contains games that have been pasted or imported temporarily. Unlike regular database tabs that are linked to PGN files on your computer, the Clipboard database itself does not exist as a file on disk. It's a special temporary database perfect for quickly pasting PGN games into the app. You can save its contents to a new PGN file at any time using File → Save PGN Database as... (Ctrl+Shift+S / ⌘+Shift+S), or clear it at any time using File → Clear Clipboard Database (Ctrl+Alt+C / ⌘+Alt+C).
• File-Based Database Tabs: Each opened PGN file appears as a separate tab, labeled with the filename (without extension). You can open multiple PGN files simultaneously, each in its own tab.
• Search Results Tab: When you perform a search across databases, the results appear in a dedicated "Search Results" tab. This tab includes an additional "Source DB" column showing which database each game came from.
• "+" Tab: Always appears last. Clicking this tab opens the file dialog to add a new PGN database to the panel.

Each tab displays a pulsing orange dot indicator when the database has unsaved changes. This visual reminder helps you track which databases need to be saved. The indicator appears next to the tab label and pulses continuously until the database is saved.

Right-clicking a database tab opens a context menu with Close (close that database) and Close all but this (close all other database tabs, keeping only the one you clicked).

4.4.2 Game Table

Each database tab displays a table listing all games in that database. The table includes the following columns:

• #: Game number within the database
• ●: Indicates which games have unsaved changes
• White: White player's name
• Black: Black player's name
• WhiteElo: White player's ELO rating
• BlackElo: Black player's ELO rating
• Result: Game result (1-0, 0-1, 1/2-1/2, or *)
• Date: Game date
• Event: Tournament or event name
• Site: Location where the game was played
• Moves: Number of moves in the game
• ECO: Opening classification code
• TimeControl: Time control from the PGN (e.g. "60+30")
• TC Type: Time control type (e.g. blitz, rapid, classical)
• Analyzed: Indicates whether the game has been analyzed
• Annotated: Indicates whether the game has custom CARA annotations (distinct from regular PGN notation annotations)
• Source DB: (Search Results only) Shows which database the game originated from
• Ref Ply: (Search Results only) Reference move (ply) when results point to a specific move in a game—for example when you use "View" in Player Stats to open games at a blunder, miss, or brilliancy.
• PGN: Full PGN notation for the game

4.4.3 Interacting with the Table

You can interact with the game table in several ways:

• Selecting Games: Click a row to select a single game. Use Shift+Click to select a range of games, or Ctrl+Click / ⌘+Click to select multiple individual games.
• Opening Games: Double-click any row to open that game in the main panel for review and analysis. The chessboard, moves list, and all other views update to show the selected game.
• Sorting: Click any column header to sort the table by that column. Click again to reverse the sort order. The sort indicator arrow shows the current sort column and direction.
• Resizing Columns: Drag the borders between column headers to resize columns. Most columns can be resized, while the PGN column always stretches to fill the remaining space.

Right-click context menu: Right-clicking anywhere in the game table opens a context menu with the following options:

• Select rows: A submenu with these options:
  • Select mode: Choose whether selection actions replace the current selection (Replace, default) or add to it (Append).
  • Select all rows / Unselect all rows: Select every row in the table or clear the selection.
  • Invert Selection: Selected rows become unselected; unselected rows become selected.
  • By column value: Select rows based on column values, with different matching options.
  • With this tag / Without this tag: When you right-click a game tag chip in the table, the submenu also offers quick options to select rows that have (or don’t have) that same tag.
• Copy table as CSV / Copy table as TSV: Copy the entire table to the clipboard in CSV or tab-separated format.
• Copy selected rows as CSV / Copy selected rows as TSV: Copy only the currently selected rows in CSV or tab-separated format.
• Copy Game: Copy the PGN of the game in the row you right-clicked (single game) to the clipboard.
• Copy selected Games / Cut selected Games: Copy or cut the PGN of all selected games to the clipboard. Cut also removes them from the database (unsaved until you save).
• Paste Game(s): Paste PGN from the clipboard into this database tab.

4.4.4 Panel Management

The Database Panel can be collapsed to maximize space for the main and detail panels. Double-click the horizontal splitter handle above the panel, or use View → Hide Database Panel (Ctrl+Shift+D / ⌘+Shift+D) to toggle its visibility. When collapsed, the panel is minimized to a thin strip, and you can expand it again using the same method.

The panel automatically updates when games are added, removed, or modified in any database. Changes are reflected immediately in the table view, and unsaved indicators appear as needed to help you track which databases contain games with unsaved changes.

4.4.5 Common Database Actions

You can perform common database operations using the File menu or keyboard shortcuts:

• Open PGN Database: Use File → Open PGN Database (Ctrl+O / ⌘+O) to open one or multiple PGN files. In the file dialog, you can select multiple files by clicking and dragging, holding Ctrl / ⌘ for individual selection, or Shift for range selection. Each file appears as a separate tab in the Database Panel.
• Open Recent: Use File → Open Recent to reopen a recently opened PGN database by filename. Missing files are marked (missing) and cannot be opened. Use Clear in the submenu to empty the list.
• Save PGN Database: Use File → Save PGN Database (Ctrl+S / ⌘+S) to save the active database. This overwrites the existing database file with the current contents.
• Save PGN Database as...: Use File → Save PGN Database as... (Ctrl+Shift+S / ⌘+Shift+S) to save the active database as a new copy.
• Close PGN Database: Use File → Close PGN Database (Ctrl+W / ⌘+W) to close the active database tab.
• Close All PGN Databases: Use File → Close All PGN Databases (Ctrl+Alt+W / ⌘+⌥+W) to close all file-based database tabs. The Clipboard and Search Results tabs are preserved.

4.5 Detail Panel

The Detail Panel contains the PGN Notation Pane at the top and a set of tabbed views below for detailed analysis.

The PGN Notation Pane displays the complete PGN notation for the current game. The PGN notation contains several different types of elements:

• Moves: The actual chess moves displayed in standard algebraic notation (e.g., e4, Nf3, O-O). These are the main-line moves that make up the game sequence.
• Comments: Text annotations that explain moves or positions. Comments can appear after moves or at the beginning of variations to provide additional context or analysis.
• Variations: Also called branches, these show alternative lines of play. Variations are enclosed in parentheses and represent moves that could have been played instead of the main-line moves.
• Annotations: Move quality assessments that include symbol-based annotations (!, !!, ?, ??, !?, ?!) and NAGs (Numeric Annotation Glyphs). When PGN files are loaded, symbol-based annotations are automatically converted to NAGs (Numeric Annotation Glyphs) by the PGN parser, and both are displayed as readable text descriptions in parentheses (e.g., "good move", "poor move", "very good move", "very poor move", "speculative move", "questionable move", "White has a slight advantage").
• Non-standard tags: Special tags that some chess software uses to encode additional information within comments, such as clock times, position evaluations, or material balance data. These appear as codes like [%evp] and [%mdl] within comment text.
• Metadata tags: PGN header tags (Event, Site, Date, White, Black, Result, ECO, etc.) that provide information about the game, players, and tournament details.
• Game result: The final outcome of the game (1-0 for White wins, 0-1 for Black wins, 1/2-1/2 for a draw).

The content is displayed in a formatted, color-coded view with syntax highlighting to distinguish between different elements.

As you navigate through the game using the ← (Left Arrow) and → (Right Arrow) keys, the active move is highlighted in the PGN notation. A single click on any main-line move jumps to that position.

Navigating into variations: By default, ← / → and clicks stay on the main line—single clicks on variation moves do not change the position. Enable PGN → Enable navigating into variations (also available from the PGN notation context menu) to browse sidelines:

• Click a variation move in the PGN pane to jump to that sideline position.
• → (Right Arrow) advances along the active line. When several continuations exist from the current node, a small branch selector appears: use ↑ / ↓ to highlight a choice, → / Enter to take it, and ← / Esc to dismiss the overlay. The mainline continuation is listed first, separated visually from the sideline options.
• ← (Left Arrow) steps back along the active path (including within a variation).
• At the end of a variation, the first → does nothing; a second → jumps to the mainline move at the fork (the move that was played in the game instead of the variation start).
• While on a sideline, the chessboard uses its variation appearance (see section 4.3.1). Manual analysis and the evaluation bar follow the variation position as well.
• The Moves List and other mainline-oriented views stay on the mainline ancestor while you browse a sideline.

Turning variation navigation off (or hiding variations with PGN → Show Variations) snaps you back to the mainline ancestor of the current path if you were on a sideline.

With PGN → Show Comments enabled, double-click inside a main-line comment (text in curly braces on the main line) to open the move-comments editor for that full move. For what the dialog contains and how changes are saved, see Editing move comments in section 4.5.1.

Context menu: You can also right-click inside the PGN notation pane to open a context menu with quick access to common PGN actions. These entries mirror the corresponding options from the menu bar.

You can control what elements are displayed in the PGN Notation Pane using the PGN menu. The following options are available:

• PGN → Show PGN header tags (Ctrl+M / ⌘+M): Toggle display of PGN header tags (Event, Site, Date, etc.)
• PGN → Show Comments (Ctrl+Shift+M / ⌘+Shift+M): Toggle display of move comments
• PGN → Show Variations (Ctrl+Shift+V / ⌘+Shift+V): Toggle display of move variations
• PGN → Show Non-Standard Tags (Ctrl+Shift+T / ⌘+Shift+T): Toggle display of non-standard tags like [%evp] and [%mdl] within comments
• PGN → Show Annotations (Ctrl+Shift+A / ⌘+Shift+A): Toggle display of move annotations, including symbol-based annotations (!, !!, ?, ??, !?, ?!) and NAGs (Numeric Annotation Glyphs).
• PGN → Show Results (Ctrl+R / ⌘+R): Toggle display of game results (1-0, 0-1, 1/2-1/2)
• PGN → Indent variations: Show each variation on its own indented line by nesting depth (display only; copy and export keep the original PGN layout). Especially useful together with navigating into variations
• PGN → Enable navigating into variations: Allow keyboard and click navigation into PGN sidelines (branch selector, variation board appearance)
• PGN → Display NAG move assessments as...: Choose between displaying NAGs as symbols (??, ?, ?! ..) or as text descriptions

The PGN menu also provides options to permanently remove elements from the game's PGN. The following options are available:

• PGN → Remove Comments: Permanently remove all comments from the game's PGN notation
• PGN → Remove Variations: Permanently remove all move variations from the game's PGN notation
• PGN → Remove Non-Standard Tags: Permanently remove non-standard tags (like [%evp] and [%mdl]) from comments in the game's PGN
• PGN → Remove Annotations: Permanently remove all move annotations (symbols and NAGs) from the game's PGN notation

These changes modify the game's actual PGN content which will persist when you save the database.

Below the PGN Notation Pane, the Detail Panel contains seven tabs, each offering distinct functionality for analyzing and working with the active game:

4.5.1 Moves List

The Moves List tab displays all moves in a table format with comprehensive per-move information: move notation, evaluations, move classifications, best move alternatives, Centipawn Loss (CPL) values, engine depth, material counts, FEN positions, and more. You can customize which columns are visible and their order using column profiles. The active move is highlighted as you navigate; click any move to jump to that position in the game. Access this tab using View → Moves List or press F1.

Editing move comments: Main-line comments for White and Black half-moves are edited in a dedicated dialog. Double-click the Comment column for a row, or right-click that cell and choose Edit Comments. The same dialog opens from the PGN pane when you double-click a main-line comment, as described in section 4.5. The dialog shows the move number and SANs, with separate text areas for White's and Black's comments; if the game ends on White's move, the Black field is disabled. OK applies changes to the game's PGN; Cancel discards them. Save the database (for example File → Save) to persist changes to disk.

The application comes with several pre-configured column profiles that organize the available columns for different analysis purposes. Switch between profiles using the number keys 1 through 9 (assigned to the first nine profiles in order), or select them from the Moves List menu. The following default profiles are available:

• Default (1): A minimal view showing only the move number, White and Black moves, and comments. Use this profile when you want a clean, uncluttered view focused on the moves themselves.
• Moves and Opening Info (2): Displays moves along with ECO codes and opening names. This profile is useful for studying opening theory and identifying which openings were played in your games.
• Game Analysis - Full (3): Shows the most important analysis columns for both White and Black moves, including evaluations, CPL values, move assessments, best move alternatives, engine depth, and top-3 move indicators. Use this comprehensive profile when you want to analyze both sides' play in detail, comparing evaluations and move quality for the entire game.
• Game Analysis - White Side (4): Focuses exclusively on White's moves and their analysis. All White-related columns are visible (evaluations, CPL, assessments, best moves, depth), while Black's analysis columns are hidden. This profile is ideal when you played White and want to focus on analyzing your own moves without the distraction of your opponent's move evaluations.
• Game Analysis - Black Side (5): Focuses exclusively on Black's moves and their analysis. All Black-related columns are visible, while White's analysis columns are hidden. Use this profile when you played Black and want to concentrate on your own moves.

You can modify any of these default profiles or create your own custom profiles. For smaller adjustments, you can reorder columns by dragging and dropping column headers in the moves list, resize columns by dragging column borders, and show or hide columns using the Moves List menu. For configuring multiple columns at once, use Moves List → Setup Profile... which provides a convenient dialog for managing all column settings. After making changes, save them with Moves List → Save Profile (to update the current profile) or Moves List → Save Profile as... (to create a new profile with a custom name). Custom profiles you create will also be accessible via number keys 1 through 9 based on their position in the profile list.

Right-clicking in the table opens a context menu to copy the cell value under the cursor or to export the table as CSV or TSV (visible columns only or all columns).

For a complete reference of all available columns and their descriptions, see section 7.7 "Moves List Columns Reference".

4.5.2 PGN header tags

The PGN header tags tab displays all PGN header tags for the current game in an editable table format. You can view, edit, add, and remove PGN header tags. Common tags include Event, Site, Date, Round, White, Black, Result, ECO, WhiteElo, and BlackElo. Changes are applied to the game's PGN data in memory. The database is marked as having unsaved changes, and your modifications will be persisted to the database file when you save it. Access this tab using View → PGN header tags or press F2.

To edit a tag value, double-click on the value cell in the table and type the new value. Tag names cannot be edited, but you can remove a tag and add a new one with a different name if needed. To add a new tag, click the Add button at the top of the metadata view, enter the tag name and value in the dialog, then click OK. To remove a tag, select the tag row in the table and click the Remove button. You will be asked to confirm the removal. Note that some tags (such as CARA analysis and annotation tags) are read-only and cannot be edited or removed.

4.5.3 Manual Analysis

The Manual Analysis tab provides continuous engine analysis of the current position with MultiPV (Multiple Principal Variations) support. Access this tab using View → Manual Analysis or press F3. While analysis is running, the engine follows the position shown on the board—including variation (sideline) positions when PGN → Enable navigating into variations is on.

Note: Manual analysis requires a chess engine to be assigned to the manual analysis task. See section 5.1 for instructions on configuring engines.

MultiPV Analysis: The standard analysis mode displays multiple candidate moves and their evaluations. You can analyze any number of principal variation lines simultaneously, each displaying the engine's recommended moves, evaluations, and depths. The first three PV lines (PV1, PV2, PV3) have color-coded indicators in the analysis display that match the colors of the corresponding arrows on the chessboard when enabled. This visual connection helps you quickly identify which analysis line corresponds to which arrow on the board. Right-clicking on a PV line opens a context menu so you can copy that PV line or all PV lines to the clipboard. The following options are available:

• Manual Analysis → Start Manual Analysis (Alt+M / ⌥+M): Start or stop continuous engine analysis of the current position
• Manual Analysis → Freeze Analysis: Hold the currently displayed PV lines and statistics while the engine continues searching in the background. Unfreeze to resume live updates
• Manual Analysis → Add PV Line (Alt+N / ⌥+N): Add an additional principal variation line
• Manual Analysis → Remove PV Line (Alt+R / ⌥+R): Remove the last added PV line (requires at least two lines)
• Manual Analysis → Enable miniature preview: Toggle display of a miniature board preview when hovering over PV moves
• Manual Analysis → Show W/D/L probabilities: When enabled and the assigned engine reports UCI W/D/L for the best line (PV1), show a win/draw/loss probability bar above the PV lines

Win / Draw / Loss bar: Engines that support UCI_ShowWDL (for example recent Stockfish and Lc0 builds) can report white/draw/black probabilities for the best principal variation. CARA displays these as a stacked bar labeled “Win probability (best engine play)”. These values reflect strong engine self-play outcomes from the current position under best play—not human opening statistics or a claim of perfect play. If the engine does not emit WDL, the bar stays hidden.

Positional Plan Exploration: This unique feature helps you understand the engine's positional plans by visualizing where the engine wants to move specific pieces and how they coordinate through the recommended sequence. Instead of just seeing individual moves, you can see the complete trajectory of each piece—where it starts, where it moves to, and the path it takes through multiple moves. The system automatically identifies the pieces that move most frequently in each PV line and tracks their movement patterns. Each of these selected pieces is assigned a distinct color and highlighted in that color in the PV display, while on the chessboard, their trajectories are visualized as colored lines connecting the squares each piece visits through the engine's suggested sequence. This helps you recognize positional themes, piece coordination patterns, and strategic plans that might not be immediately obvious from traditional engine analysis alone.

The following options are available:

• Manual Analysis → Explore PV1 Positional Plans: Enable plan exploration for the first principal variation line
• Manual Analysis → Explore PV2 Positional Plans: Enable plan exploration for the second principal variation line
• Manual Analysis → Explore PV3 Positional Plans: Enable plan exploration for the third principal variation line
• Manual Analysis → Max number of pieces to explore: Configure how many pieces to track in the trajectory visualization (1-3 pieces). The system selects the pieces that move most frequently in the PV line up to this limit
• Manual Analysis → Max Exploration depth: Set the exploration depth for piece trajectories (2-4 moves ahead), determining how many moves into the future the trajectory visualization extends

4.5.4 Opening Explorer

The Opening Explorer tab helps you study the opening path to the current position and book continuations from here. Access this tab using View → Opening Explorer or press F4.

The view has two main parts:

• Lines until here: The sequence of book (and out-of-book) steps from the start position to the active ply. Each step can show a small board in the current theme (piece set, colors, and orientation match the main board). Click a step to jump to that position in the game. Use the ↗ control to open the corresponding position in the Lichess opening explorer in your browser.
• Lines from here: Continuations suggested by CARA's ECO opening database from the current position. Expand a move to browse deeper book lines.

When an encyclopedia article is available for a named opening on the path or among the continuations, an information control (ⓘ) appears next to that name so you can open the article directly. See the next section.

4.5.4.1 Opening Encyclopedia

The Opening Encyclopedia provides articles for many well-known openings and variations. Each article includes a short introduction, a Key ideas section, Name origin and History sections, and up to two illustrative images, so you can learn more about an opening that you encountered in one of your games or that you discovered in the Opening Explorer.

To open the encyclopedia, look for the small ⓘ symbol next to the opening name in the Game Information header above the board or the opening entries in the Opening Explorer pane.

CARA tries to open the article that matches the specific opening line whenever possible. If that exact variation is not yet covered, it falls back to an earlier related variation in the same opening family. When that happens, a Fallback tag appears under the title so you can see that the article shown is for a related parent line rather than a dedicated entry for the exact variation.

Use the search icon in the dialog header to look up other openings by name or ECO code. Common abbreviations such as KID (King's Indian Defense) are recognized, and you can refine them further (for example KID b3). Click a result to open that article. When many openings match, CARA shows a short list and notes how many further matches were found.

4.5.5 Game Summary

The Game Summary tab provides a comprehensive overview of the current game by synthesizing data from the Game Analysis function into key performance indicators (KPIs) and valuable insights. Access this tab using View → Game Summary or press F5.

Evaluation Graph: At the top of the view, a visual graph shows how the position evaluation changed throughout the game over time. The graph includes indicators marking phase transitions (opening to middlegame, middlegame to endgame) and highlights the worst and best moves for each player, making it easy to see critical moments and how the game's balance shifted. The graph is displayed in a resizable panel that can be adjusted to show more or less detail.

The evaluation graph supports two display modes that you can toggle using Game Analysis → Normalized Evaluation Graph (Ctrl+Shift+N / ⌘+Shift+N):

• Zero-based mode: In this mode, 0.00 (equal position) is displayed at the bottom of the graph. Positive evaluations (White advantage) extend upward, and negative evaluations (Black advantage) extend downward from the zero line.
• Normalized mode: In this mode, 0.00 (equal position) is displayed in the middle of the graph with a symmetric scale. This mode is particularly useful for games with large evaluation swings, as it provides better visual balance and makes it easier to see relative changes in evaluation throughout the game.

Key Statistics: The summary displays per-player statistics for both White and Black, including:

• Accuracy percentage: Overall move quality score based on analysis
• Average Centipawn Loss (CPL): Average deviation from optimal play measured in centipawns
• Estimated ELO: An estimated playing strength rating based on the player's move quality in this specific game. This is a best-effort approximation that may not accurately reflect a player's true rating, especially since it's calculated from a single game rather than a statistical sample across many games. The estimate considers average move quality, blunders, and mistakes to provide a rough indication of playing strength, but should be interpreted with caution.

Move Classification: The view displays pie charts showing the distribution of move quality throughout the game for each player. You can see how many moves were strong (Best Move, Good Move, Brilliant) versus how many were errors (Inaccuracy, Mistake, Blunder), giving you a quick visual overview of each player's performance. The charts also show book moves and missed opportunities.

Phase Analysis: The view breaks down performance for each player across the three phases of a chess game—Opening, Middlegame, and Endgame—showing how each player performed in different stages of the game. This helps you identify strengths and weaknesses in specific phases. Each phase section shows accuracy, average CPL, and move counts for that phase. The system automatically detects phase boundaries based on opening theory, material exchanges, and endgame classification. When an endgame is detected, the system also classifies the specific endgame type (such as Pawn Endgame, Rook Endgame, Minor Piece Endgame, or Queen Endgame) based on the material composition, which is displayed in the phase analysis section.

Game Highlights: The view displays detected tactical and positional patterns that occurred during the game. Highlights are organized by game phase and help you quickly identify key moments. Each highlight entry is a clickable link that navigates directly to the move where the pattern occurred, allowing you to quickly review the position and context.

Critical Moments: The summary identifies the top best and worst moves for each player, allowing you to quickly review and navigate to critical moments in the game. Each critical moment shows the move number, move notation, evaluation, and best alternative move when applicable. Each critical moment entry is a clickable link that navigates directly to that move in the game, making it easy to jump to and analyze these important positions.

Copying to clipboard: Right-click in the Game Summary view to open a context menu. You can copy the section you clicked on (e.g. Key Statistics, Phase Analysis, Critical Moments) or copy the full summary to the clipboard.

PDF report: The same context menu offers Export PDF Report, which saves a multi-page report with overview, evaluation chart, classifications, phases, highlights, and an annotated game with diagrams.

This comprehensive overview helps you quickly understand the flow of the game, identify critical moments, and assess each player's performance across different phases of play.

4.5.6 Player Stats

The Player Stats tab answers questions about a player across many games at once (not to be confused with Game Summary, which describes a single game). Open it with View → Player Stats or press F6.

In short: pick a Source (which set of games to use) and a player. Only players with at least two analyzed games in that source appear in the list, because the figures are meant to reflect a pattern rather than a single outing.

The page is made of separate sections you can turn on or off; several charts offer their own display options. For prerequisites, every section, chart interactions (such as opening games from a heatmap or a pattern), and settings in everyday language, read section 5.7 Viewing Player Statistics.

4.5.7 Annotations

The Annotations tab provides tools for creating and managing custom CARA annotations on the chessboard. Unlike regular PGN annotations, CARA annotations include free-form text that can be positioned anywhere on the board, adjusted in size and rotated.

You can also add arrows, circles, and square highlighting with customizable colors. Annotations are position-specific, attached to the current path in the game tree (mainline or variation), and are compressed and serialized in a PGN metadata tag to keep the PGN move notation clean.

Access this tab using View → Annotations or press F7.

4.5.8 AI Summary

The AI Summary tab provides an interactive chat interface for discussing any position in a game with a Large Language Model (LLM). The AI model has access to extensive game data, including detailed engine analysis, move classifications, evaluation metrics, and positional information, enabling it to provide accurate assessments of the game, played moves, and current position. You can ask questions about the game, request explanations of moves, or generate summaries. Access this tab using View → AI Summary or press F8.

CARA supports OpenAI, Anthropic, and custom OpenAI-compatible endpoints. Configure your provider and API key through the AI Model Settings dialog; see section 6.12. See section 7.9 for more information on setting up a custom endpoint.

4.5.9 Notes

Use the Notes tab to keep your own comments, plans, or post-mortem thoughts with a game.

When you type move notation (e.g. 1. e4, 13... Rb7), CARA recognizes it and formats it for you. Moves that were actually played in the current game become clickable links—click one to jump to that position. Other move notation (for example from variations or lines you're discussing) is shown in bold only, so it still stands out but doesn't link. That way you can refer to specific moves or positions and jump straight to them when the move is in the game.

Markdown formatting in Notes: Use the formatting toolbar above the editor to apply a small Markdown subset to the currently selected text. Supported syntax:

• Headings: # , ## , ### at the start of a line (H1/H2/H3 buttons).
• Bold: **text** (also supported: __text__).
• Italic: *text* (also supported: _text_).
• Bold + italic: ***text*** (also supported: ___text___).
• Inline code: `code`.
• Strikethrough: ~~text~~.
• Blockquote: > text at the start of a line.

To attach your text to the current game, use Notes → Save Notes to current game (Ctrl+Alt+N). To remove the notes for the current game, use Notes → Clear Notes for current game (Ctrl+Shift+E). Notes are written to the PGN when you save the database.

Open the Notes tab from View → Notes or press F9.

4.6 Keyboard Shortcuts

Below you can find a list of the most common keyboard shortcuts (application defaults), allowing you to work efficiently with the features described in this section. You can customize these bindings in CARA—see section 6.14.2. For a complete reference of all default keyboard shortcuts organized by category, see section 6.16.

4.6.1 Navigation

• ← (Left Arrow): Navigate to the previous move along the active path (main line, or within a variation when variation navigation is enabled)
• → (Right Arrow): Navigate to the next move along the active path; with variation navigation enabled, opens the branch selector when multiple continuations exist
• Shift+←: Jump to the starting position of the game
• Shift+→: Jump to the last move of the main line
• ↑ / ↓: While the branch selector is open, move the highlight among choices
• Enter: While the branch selector is open, take the highlighted continuation (→ also confirms)
• Esc: Dismiss the branch selector without moving (← also dismisses)

4.6.2 Board Controls

• X: Rotate the board 180 degrees
• Alt+C / ⌥+C: Toggle coordinates display
• Alt+T / ⌥+T: Toggle turn indicator
• Alt+P / ⌥+P: Toggle played move arrow
• Alt+B / ⌥+B: Toggle best next move arrow (PV1)
• Alt+2 / ⌥+2: Toggle PV2 arrow
• Alt+3 / ⌥+3: Toggle PV3 arrow
• Alt+A / ⌥+A: Toggle best alternative move arrow
• Alt+H / ⌥+H: Toggle positional heatmap
• Alt+E / ⌥+E: Toggle evaluation bar
• Alt+U / ⌥+U: Toggle material widget
• Alt+I / ⌥+I: Toggle game information display
• Alt+L / ⌥+L: Toggle annotations layer

4.6.3 Database Operations

• Ctrl+Shift+F / ⌘+Shift+F: Search games across databases
• Ctrl+Shift+W / ⌘+Shift+W: Close search results
• Ctrl+Shift+I / ⌘+Shift+I: Import online games
• Ctrl+Shift+B / ⌘+Shift+B: Bulk Operations
• Ctrl+Shift+U / ⌘+Shift+U: Deduplicate games

4.6.4 Detail Panel Tabs

• F1: Switch to Moves List tab
• F2: Switch to PGN header tags tab
• F3: Switch to Manual Analysis tab
• F4: Switch to Opening Explorer tab
• F5: Switch to Game Summary tab
• F6: Switch to Player Stats tab
• F7: Switch to Annotations tab
• F8: Switch to AI Summary tab
• F9: Switch to Notes tab

4.6.5 Game Analysis

• Ctrl+G / ⌘+G: Start game analysis for the current game
• Escape: Cancel ongoing game analysis
• Ctrl+Shift+N / ⌘+Shift+N: Toggle normalized evaluation graph mode
• Ctrl+Shift+K / ⌘+Shift+K: Configure move classification settings

4.6.6 Manual Analysis

• Alt+M / ⌥+M: Start or stop continuous engine analysis of the current position
• Alt+N / ⌥+N: Add an additional principal variation line
• Alt+R / ⌥+R: Remove the last added PV line

4.6.7 File Operations

• Ctrl+O / ⌘+O: Open PGN database
• Ctrl+S / ⌘+S: Save active PGN database
• Ctrl+Shift+S / ⌘+Shift+S: Save active PGN database as...
• Ctrl+W / ⌘+W: Close active PGN database
• Ctrl+Alt+W / ⌘+⌥+W: Close all PGN databases
• Ctrl+Q / ⌘+Q: Close application

4.6.8 Edit Operations

• Ctrl+V / ⌘+V: Paste PGN to active database
• Ctrl+Alt+V / ⌘+⌥+V: Paste PGN to Clipboard database
• Ctrl+P / ⌘+P: Copy PGN to clipboard
• Shift+F: Copy FEN to clipboard
• Ctrl+F / ⌘+F: Paste FEN to board
• Ctrl+C / ⌘+C: Copy selected games
• Ctrl+X / ⌘+X: Cut selected games

4.6.9 PGN Display Options

• Ctrl+M / ⌘+M: Toggle metadata display
• Ctrl+Shift+M / ⌘+Shift+M: Toggle comments display
• Ctrl+Shift+V / ⌘+Shift+V: Toggle variations display
• Ctrl+Shift+T / ⌘+Shift+T: Toggle non-standard tags display
• Ctrl+Shift+A / ⌘+Shift+A: Toggle annotations display
• Ctrl+R / ⌘+R: Toggle results display

4.6.10 Moves List Profiles

• 1 - 9: Switch to column profile 1 through 9
• Ctrl+Shift+P / ⌘+Shift+P: Save current profile
• Ctrl+Alt+P / ⌘+⌥+P: Save current profile as...
• Ctrl+Shift+Delete / ⌘+Shift+Delete: Remove current profile

4.6.11 Annotations

• Ctrl+Alt+S: Save annotations
• Ctrl+Shift+D / ⌘+Shift+D: Clear all annotations
• Ctrl+Alt+D: Clear move annotations

4.6.12 View Options

• Ctrl+Shift+D / ⌘+Shift+D: Toggle database panel visibility

4.6.13 Notes

• Ctrl+Shift+E: Clear notes for current game
• Ctrl+Alt+N: Save notes to current game

4.6.14 Engine Configuration

• Ctrl+E: Add or configure chess engine

4.7 Your First Game Analysis

Follow these steps to analyze your first game:

1. Ensure you have a chess engine configured:
   Before starting, make sure you have at least one UCI-compatible chess engine added to CARA. See section 5.1 for instructions on configuring engines. For engine suggestions, see section 7.10.
2. Open a game or paste PGN:
   Open a PGN database using File → Open PGN Database (Ctrl+O / ⌘+O), or paste PGN text into the Clipboard database using Edit → Paste PGN to Clipboard DB (Ctrl+Alt+V / ⌘+⌥+V)—the pasted game gets loaded automatically.
3. Switch to the Moves List view:
   Press F1 to switch to the Moves List tab, then press 3 to select the "Game Analysis - Full" profile. This profile displays all the important analysis columns you'll need to review the game.
4. Start the game analysis:
   Press Ctrl+G / ⌘+G (or use Game Analysis → Start Game Analysis) to begin analyzing the game. Watch as the moves list fills in with evaluation data, move classifications, CPL values, and best move alternatives as the analysis progresses. Progress and estimated time remaining are shown in the status bar.
5. Review the results:
   Once analysis completes, you can review the per-move analysis directly in the Moves List, or press F5 to switch to the Game Summary tab for a condensed overview showing key statistics, the evaluation graph, critical moments, and detected game highlights.

5.1 Configuring Engines

CARA requires at least one UCI-compatible chess engine to perform game analysis. Adding your first engine is straightforward and doesn't require any special configuration—default settings are usually sufficient to get started.

There are two general types of chess engines you can use with CARA:

• Conventional alpha-beta search engines (e.g., Stockfish, Berserk, Komodo): These engines use traditional search algorithms and are typically faster, making them ideal for quick analysis and when you need responsive performance. They work well on standard CPUs and don't require specialized hardware.
• Neural network-based engines (e.g., Leela Chess Zero, Maia): These engines use machine learning models and often provide different evaluation perspectives compared to conventional engines. They are generally slower than conventional engines and may benefit from a powerful graphics card (GPU) for optimal performance. They can be useful when you want alternative analysis perspectives on positions. For example, with sufficient hardware, you can use neural network-based engines with the manual analysis function to get a different perspective than you would from using a conventional engine.

For a short, consistent list of engine suggestions (free and commercial) and best use cases inside CARA, see section 7.10.

5.1.1 Adding Your First Engine

To add your first engine:

1. Open the engine dialog:
   Use Engines → Add Engine... or press Ctrl+E.
2. Select the engine executable:
   Click "Browse" to locate your chess engine executable file (e.g., stockfish.exe on Windows, or stockfish on Linux/macOS).
3. Validate the engine:
   CARA will automatically validate that the engine supports the UCI protocol. The engine name, author, and version will be detected automatically.
4. Add the engine:
   Click "Add" to add the engine. The first engine you add will automatically be assigned to all analysis tasks (game analysis, evaluation, manual analysis, and brilliancy detection), so you can start analyzing games immediately. You can reassign this engine or add additional engines later (see section 5.1.2).

5.1.2 Adding Additional Engines and Advanced Configuration

Once you have your first engine set up, you can add additional engines and configure per-engine, per-task settings to optimize performance for different analysis scenarios:

• Multiple engines: You can add multiple engines and assign different engines to different tasks. For example, you might use a fast engine for continuous evaluation and a stronger engine for deep game analysis, or a separate engine for brilliancy detection.
• Task assignment: Under Engines → [Engine Name] you can assign the engine to one or more tasks. Use Set for all tasks to assign that engine to every task (game analysis, evaluation, manual analysis, and brilliancy detection) in one step. Alternatively, use the individual items Set as Game Analysis Engine, Set as Evaluation Engine, Set as Manual Analysis Engine, and Set as Brilliancy Detection Engine. Only one engine can be assigned to each task at a time.
  
• Per-task configuration: Each engine can have separate settings for each task (evaluation, game analysis, manual analysis, and brilliancy detection). Use Engines → [Engine Name] → Engine Configuration... to open a dialog with one tab per task. There you can set thread count, depth limits, time limits, and engine-specific options for each task independently.
  

  The dialog includes "Copy" and "Paste" buttons on each tab so you can copy settings from one task to another. The "Reset to Defaults" button restores the recommended default settings for all tasks.

  Quick Tip: Per-task engine configuration is optional. For most users, the default configurations will work fine.

5.2 Importing Games

CARA provides several ways to import and open games. This section covers the three main methods.

5.2.1 Copy from System Clipboard

The quickest way to import a single game is to paste PGN text directly from your system clipboard:

1. Copy PGN text:
   Copy PGN game data from any source (website, text file, another application) to your system clipboard.
2. Paste into CARA:
   Use Edit → Paste PGN to Clipboard DB (Ctrl+Alt+V / ⌘+⌥+V) to paste into the Clipboard database, or Edit → Paste PGN to active DB (Ctrl+V / ⌘+V) to paste into the currently active database. The pasted game gets loaded automatically and becomes the active game.

5.2.2 Open PGN File(s)

To import games from one or more PGN files on your computer:

1. Open the file dialog:
   Use File → Open PGN Database (Ctrl+O / ⌘+O) to open the file selection dialog.
2. Select files:
   Select one or multiple PGN files from your computer. You can select multiple files using several methods: click and drag with your mouse to select a range of files, hold Ctrl on Windows or ⌘ on macOS while clicking to select individual files, or hold Shift while clicking to select a range of files.
3. Load games:
   Each selected file opens as a separate tab in the Database Panel. The first game from the first file automatically becomes the active game.

To reopen a database you used earlier, choose it from File → Open Recent.

5.2.3 Import from Online Platforms

CARA can import games directly from online chess platforms:

1. Open the import dialog:
   Use File → Import Games from Online... (Ctrl+Shift+I / ⌘+Shift+I) to open the import dialog.
2. Select platform and enter username:
   Choose either Lichess or Chess.com, then enter the username of the player whose games you want to import.
3. Configure import options (optional):
   You can optionally filter games by date range, game type (blitz, rapid, classical, etc.), and set a maximum number of games to import.
4. Choose destination:
   Select whether to import games into the Clipboard database or the currently active database.
5. Start import:
   Click "Import" to begin. CARA will fetch games from the platform's API and display progress in the status bar. Once complete, the imported games are added to your selected database.

5.3 Managing Databases

CARA provides several tools for managing your game databases, including basic file operations and Bulk Operations for batch processing multiple games at once.

5.3.1 Basic Database Operations

For opening, saving, and closing databases, see section 4.4.5.

5.3.2 Game Tags

Game tags are simple labels you can assign to a game so you can organize and recognize games quickly (for example “Training”, “Tournament”, “Must review”, “Opening prep”). They are separate from the PGN header tags (like Event, Site, White, etc.).

CARA distinguishes two kinds of game tag definitions:

• Built-in game tags — A fixed set of tag names and default colors supplied with the application (including tags that auto-tagging can assign). You cannot rename or delete them, but in Game tags → Manage game tags… you can change their color and hide or show each built-in tag. Your overrides are saved in your user settings.
• Custom game tags — Tags you add yourself (name and color). You can remove a custom tag definition from the same dialog.

If you hide a built-in tag, it no longer appears in the tag picker: not in the Game Tags widget, not in the Game tags column of the database table, and not in the checkable entries under Game tags on the menu bar (or the widget’s context menu). Hidden tags can still be listed in Game tags → Manage game tags… so you can turn them back on or adjust their color.

Game tags are shown as small chips in the database view and in the Game Tags widget next to the chessboard (when visible).

To assign tags to the active game, right-click inside the Game Tags widget and toggle tags in the list, or use the Game tags menu on the menu bar. In Game tags → Manage game tags…, hover a custom tag chip to reveal a color control and a remove control; built-in chips use color and visibility (eye) controls instead.

5.3.3 Bulk Operations

Use File → Bulk Operations... (Ctrl+Shift+B / ⌘+Shift+B) to update PGN header tags and clean game notation across many games in one pass.

The dialog is organized into three groups:

• Target Games: Choose All games in the active database, or Selected games in the database table.
• Operations: Your ordered list of steps. Use the toolbar icons to add, edit, or remove an operation, clear the list, or save and load named plans.
• Smart Update: Optional Result and ECO updates that run in addition to your operations list (they are not stored in saved plans).

To add an operation, use the add button in the Operations toolbar. In the editor, choose an Operation type, fill in the fields that appear for that type, then click Add (or Save when editing). Operations run from top to bottom in the order shown in the list.

Available operation types:

• Replace PGN header tag values: Find and replace text in one or more tags (for example White, Black, Event, or Site). Use Case sensitive and Use regex when you need stricter or pattern-based matching. With Use regex enabled, the Preset list offers starting patterns for common tasks (for example Remove matched text or Keep text before "-"); choose Custom… to enter your own pattern.