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.

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. The application supports multiple chess engines via the UCI (Universal Chess Interface) protocol, so you can use any UCI-compatible engine (for example Stockfish, Lc0, Komodo, Shredder).

If you’re not sure what to install, see section 7.10 “Recommended Chess Engines”.

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 streamline common tasks: replace tags across multiple games, clean and format PGN content, and perform batch modifications. 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. 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.
• 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 individual moves in the game, 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: 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.
• 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 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. We extend our thanks to Cburnett and the Wikimedia Commons community 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 all UI styling, layout dimensions, colors, fonts, and application-wide default settings. This file is located in the app/config/ directory and defines the visual appearance and behavior of the application. You can customize CARA's appearance by modifying this file without changing any source code.
• user_settings.json: Stores your personal preferences and settings, including moves list column profiles, board visibility settings, PGN display options, engine configurations, 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.

All aspects of CARA's appearance can be customized through the config.json configuration file. This includes fonts, colors, sizes, dimensions, panel layouts, and all UI styling. The configuration system follows a strict structure with no hardcoded values in the application code, allowing you to completely customize the application's appearance without modifying any source code.

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.

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, 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 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.

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.
• 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")

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.

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 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.6 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.7 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+Shift+C / ⌘+Shift+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.
• 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. Single clicks on variation moves, comment text, or metadata tags do not change the current position.

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 → 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.

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 → 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

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 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 F4.

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.

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.5 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 F5.

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.6 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 individual moves in the game, 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 F6.

4.5.7 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 F7.

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.8 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 F8.

4.6 Keyboard Shortcuts

Below you can find a list of the most common keyboard shortcuts, allowing you to work efficiently with the features described in this section. For a complete reference of all keyboard shortcuts organized by category, see section 6.15.

4.6.1 Navigation

• ← (Left Arrow): Navigate to the previous move in the game
• → (Right Arrow): Navigate to the next move in the game

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+R / ⌘+Shift+R: Bulk replace in databases
• Ctrl+Alt+T / ⌘+⌥+T: Bulk tag games
• Ctrl+Shift+L / ⌘+Shift+L: Bulk clean PGN
• 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 Game Summary tab
• F5: Switch to Player Stats tab
• F6: Switch to Annotations tab
• F7: Switch to AI Summary tab
• F8: 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 Clipboard database
• Ctrl+Alt+V / ⌘+⌥+V: Paste PGN to active database
• Ctrl+P / ⌘+P: Copy PGN to clipboard
• Shift+F: Copy FEN to clipboard
• Ctrl+F / ⌘+F: Paste FEN to board
• Ctrl+Shift+C / ⌘+Shift+C: Copy selected games
• Ctrl+Shift+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+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 F4 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+V / ⌘+V) to paste into the Clipboard database, or Edit → Paste PGN to active DB (Ctrl+Alt+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.

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 powerful 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 replace PGN header tags

Use File → Bulk Replace PGN header tags... (Ctrl+Shift+R / ⌘+Shift+R) to find and replace text in PGN header tags across multiple games. This is useful for correcting typos, standardizing player names, or updating event information.

The dialog allows you to:

• Select a tag to modify (e.g., White, Black, Event, Site)
• Specify text to find and replace
• Choose between case-sensitive or case-insensitive matching
• Use regular expressions for advanced pattern matching
• Process all games or only selected games in the database table

If you enable Use regex, the Find field is treated as a regular expression. Here are a few practical examples you can try:

The dialog also includes two smart update options:

• Update Result based on last move evaluation: Analyzes the final position of each game using a chess engine to determine the game result. This option only updates games with indecisive results (empty, "*", or "?"), preserving games that already have decisive results (1-0, 0-1, 1/2-1/2). It can detect checkmate or stalemate directly, or use engine evaluation to determine the likely result for incomplete games. This is useful if you are for example importing games from a chess computer, which doesn't provide a resign function.
• Update ECO code with played opening ECO: Analyzes the opening moves of each game and updates the ECO (Encyclopaedia of Chess Openings) tag based on the opening that was actually played. This uses CARA's built-in opening database to identify the correct ECO code from the game's move sequence.

5.3.4 Bulk add/remove PGN header tags

Use File → Bulk Add/Remove PGN header tags... (Ctrl+Alt+T / ⌘+⌥+T) to add or remove PGN header tags across multiple games. This is useful for adding missing information or cleaning up tag sets.

The dialog allows you to:

• Add a new tag with a fixed value or copy from another tag
• Remove existing tags
• Process all games or only selected games in the database table

5.3.5 Bulk Clean PGN

Use File → Bulk Clean PGN... (Ctrl+Shift+L / ⌘+Shift+L) to remove unwanted elements from PGN notation across multiple games.

The dialog allows you to remove:

• Comments
• Variations
• Non-standard tags
• Annotations (e.g., !, ?, !?, ?!)
• Results

You can select any combination of these options and process all games or only selected games in the database table.

5.3.6 Deduplicate Games

Use File → Deduplicate Games in Active Database... (Ctrl+Shift+U / ⌘+Shift+U) to identify and remove duplicate games from the active database.

The deduplication dialog allows you to choose how games are matched:

• Exact PGN: Matches games with identical PGN notation (including headers, moves, comments, and variations)
• Moves Only: Matches games with identical move sequences, ignoring headers, comments, and variations
• Normalized PGN: Matches games with identical PGN after removing comments and variations
• Header Based: Matches games based on selected header fields (e.g., White, Black, Date, Result)

When duplicates are found, the active game (if it's a duplicate) is preserved, and other duplicates are removed. Progress is displayed in the status bar during the operation.

5.4 Searching Games

CARA provides powerful search functionality to find games across your databases based on multiple criteria. You can search within a single database or across all open databases simultaneously, and combine criteria using logical operators (AND/OR) and grouping.

5.4.1 Search Scope

When you open the search dialog using File → Search Games... (Ctrl+Shift+F / ⌘+Shift+F), you can choose where to search:

• Active database: Search only within the currently active database tab.
• All open databases: Search across all open database tabs simultaneously. Results from different databases are combined and displayed in a dedicated "Search Results" tab with an additional "Source DB" column indicating which database each game came from.

5.4.2 Search Criteria

Each search criterion consists of three parts:

• Field: The game property to search (e.g., White, Black, WhiteElo, BlackElo, Result, Date, Event, Site, ECO, Analyzed, Annotated, or Custom PGN Tag).
• Operator: How to compare the field value. Available operators depend on the field type:
  • Text fields (White, Black, Event, Site, ECO): contains, equals, not equals, starts with, ends with, is empty, is not empty
  • Numeric fields (WhiteElo, BlackElo): equals, not equals, greater than, less than, greater than or equal, less than or equal
  • Date field: equals, not equals, before, after, contains (for partial date matching, e.g., "2025" matches "2025.11.09")
  • Boolean fields (Analyzed, Annotated): is, is not
• Value: The value to search for (not required for "is empty", "is not empty", or boolean fields).

For "Custom PGN Tag", you must also specify the tag name in an additional field that appears when this option is selected.

5.4.3 Logical Operators and Grouping

Search criteria are combined using logical operators (AND/OR) to create complex queries. By default, criteria are combined with AND logic, meaning all criteria must match for a game to be included in the results.

Each criterion row (except the first) has an AND/OR selector that determines how it relates to the previous criterion:

• AND: Both this criterion and the previous criterion must match (default).
• OR: Either this criterion or the previous criterion (or both) must match.

5.4.4 Grouping Criteria

For more complex searches, you can group criteria together using the "Start Group" and "End Group" buttons. Groups allow you to create logical expressions like "(A AND B) OR (C AND D)".

To create a group:

1. Add criteria: Add the criteria you want to include in the group using "Add Criterion".
2. Start the group: Click "Start Group" to mark the beginning of a group. This adds a new criterion row that is visually indented and marked as the group start.
3. Add group criteria: Add additional criteria within the group. These will be visually indented to show they belong to the group.
4. End the group: Click "End Group" to mark the end of the group. The last criterion before the end marker becomes the group end.

Groups can be nested to create complex logical expressions. Nested groups are visually indicated by increased indentation levels. The search system evaluates groups from innermost to outermost, allowing you to create sophisticated queries like "((A OR B) AND C) OR (D AND E)".

When a group is created, the AND/OR operator on the group start row determines how the entire group relates to criteria before it. Criteria within a group are combined according to their individual AND/OR operators.

5.4.5 Performing a Search

Once you've set up your search criteria:

1. Review your criteria: Ensure all criteria have valid values and logical operators set correctly.
2. Click "Search": CARA will search the selected database(s) and display matching games in a "Search Results" tab in the Database Panel.
3. Review results: The search results tab shows all matching games. If you searched across multiple databases, each result includes a "Source DB" column indicating which database it came from.

The search dialog remembers your last search query during the current session, so you can easily modify and re-run searches. Double-click any game in the search results to open it for review.

5.5 Analyzing a Game

CARA's game analysis feature uses a chess engine to evaluate every move in a game, providing detailed insights into move quality, evaluation changes, and alternative moves. This section explains how to analyze a single game.

5.5.1 Starting Game Analysis

To analyze the currently active game:

1. Ensure you have a game loaded:
   Open a game from your database or paste a PGN game. The game must be active (displayed in the main panel).
2. Verify engine configuration:
   Make sure you have at least one UCI-compatible chess engine configured and assigned to the game analysis task. If you haven't configured an engine yet, see section 5.1.1 for step-by-step instructions. For information about assigning engines to specific tasks, see section 5.1.2.
3. Start the analysis:
   Use Game Analysis → Start Game Analysis (Ctrl+G / ⌘+G) to begin analyzing the game. CARA will automatically switch to the Moves List tab if configured to do so (see section 5.5.4).

During analysis, CARA processes each move sequentially, evaluating the position before and after each move, calculating Centipawn Loss (CPL), and classifying move quality. Progress is displayed in the status bar, showing the current move being analyzed, the engine name, search depth, and evaluation.

5.5.2 Understanding Analysis Results

As moves are analyzed, the Moves List shows detailed information for each move:

• Evaluation: The engine's evaluation of the position after each move (in centipawns, from White's perspective).
• Centipawn Loss (CPL): How much worse the played move is compared to the best move, measured in centipawns (where 100 centipawns = 1 pawn). Lower values are better. A CPL of 0 means the best move was played.
• Move Classification: Each move is classified as one of:
  • Book Move: A move found in the opening book database
  • Brilliant: An exceptional move identified through shallow depth analysis. See section 5.5.3 for details on how brilliancy detection works.
  • Best Move: The engine's recommended move was played
  • Good Move: A solid move with low CPL
  • Inaccuracy: A suboptimal move that loses some evaluation but doesn't significantly change the game
  • Mistake: A poor move that significantly worsens the position
  • Miss: A missed opportunity (e.g., missing a winning move or allowing a draw)
  • Blunder: A catastrophic move that dramatically changes the evaluation
• Best Alternative Move: The engine's recommended move for each position, displayed in the Moves List. The best alternative move arrow on the chessboard highlights this move visually.
• Engine Depth: The search depth reached by the engine for each position.

You can review this information in the Moves List, or switch to the Game Summary tab (F4) for a condensed overview of key game moments, statistics, and highlights.

5.5.3 Brilliant Move Detection

CARA includes a brilliancy detection system that identifies exceptional moves by analyzing them at shallow engine depths.

How Brilliancy Detection Works:

When brilliancy detection is enabled, CARA performs an additional analysis pass after the main game analysis completes. This process:

1. Identifies candidate moves: Selects moves that were classified as "Best Move" (or "Best Move" and "Good Move" depending on settings) at full analysis depth.
2. Re-analyzes at shallow depths: For each candidate move, CARA re-analyzes the position at multiple shallow engine depths (typically depths 3-7, configurable).
3. Checks for errors at shallow depths: At each shallow depth, the system checks whether the candidate move would be classified as a "Mistake" or "Blunder" if evaluated at that depth.
4. Requires agreement across depths: A move is marked as "Brilliant" only if it shows an error (Mistake/Blunder) at a minimum number of shallow depths (configurable, default: 3 depths). This ensures that the move truly appears suboptimal at shallow depths but is actually strong when analyzed more deeply.

Why This Works:

Brilliant moves often involve material sacrifices or complex tactical sequences that appear bad at shallow depths but reveal their strength when analyzed more deeply. By requiring that a move shows as an error at multiple shallow depths, the system identifies moves that are counterintuitive and require deeper calculation to appreciate.

Configuration:

Brilliancy detection can be enabled/disabled via Game Analysis → Brilliant Move Detection. The detection criteria can be customized in the Classification Settings dialog (Game Analysis → Configure Classification Settings...), including:

• Shallow Depth Min/Max: The range of shallow depths to check (default: 3-7)
• Min Agreement: Minimum number of shallow depths that must show the move as an error (default: 3)
• Move Candidate: Which moves to check - "Best Move only" or "Best or Good Move" (default: Best Move only)

See section 6.7.4 for more information about configuring brilliancy detection settings.

5.5.4 Analysis Settings

CARA provides several settings to customize the analysis workflow:

• Switch to Moves List at Start of Analysis: Automatically switches to the Moves List tab when analysis begins (enabled by default).
• Return to PLY 0 after analysis completes: Automatically navigates to the starting position (PLY 0) when analysis completes.
• Switch to Game Summary after Analysis: Automatically switches to the Game Summary tab when analysis completes.
• Store Analysis Results in PGN Tag: Saves analysis data (evaluations, CPL, classifications) in a PGN metadata tag for persistence across sessions.

These settings can be toggled in the Game Analysis menu and are saved in your user settings.

5.5.5 Auto-tagging

Auto-tagging can assign game tags automatically after game analysis (single-game and bulk). Turn it on or off with Game Analysis → Auto Tag Games (see section 6.7).

When auto-tagging is on, you can still choose which rules may apply: use Game Analysis → Select Tags for Auto-Tagging and check or uncheck each tag name. Your choices are saved with your user preferences. If every tag is unchecked, analysis will not add any of these automatic tags (existing manual tags on the game are unchanged). The submenu is available only while Auto Tag Games is enabled.

Numeric thresholds for the evaluation-based rules below are defined in config.json (under game_analysis.auto_game_tagging). The Sharp rule uses average CPL (both sides), minimum full-move rows, median engine depth and book-move share (sharp_data_quality), and is suppressed when the opening disaster, blunder-decided, or chaotic patterns would apply. The Brilliant Move auto-tag depends on moves being classified as Brilliant in the moves list, which requires Game Analysis → Brilliant Move Detection to be on and a compatible engine assignment; see section 5.5.3.

The following auto-tag rules are available:

5.5.6 Cancelling Analysis

You can cancel an ongoing analysis at any time using Game Analysis → Cancel Game Analysis or press Escape. When cancelled, analysis stops at the current move, and all moves analyzed up to that point retain their analysis data.

5.5.7 Bulk Analysis

To analyze multiple games at once, use Game Analysis → Bulk Analyze Database....

CARA automatically optimizes available CPU cores to analyze multiple games in parallel, maximizing analysis speed. Progress and estimated time remaining are displayed in the status bar, and you can cancel and resume bulk analysis at any time.

5.6 Manual Analysis

Manual Analysis provides continuous engine analysis of any position, allowing you to explore candidate moves and understand the engine's recommendations in real-time. Unlike game analysis which processes all moves in a game, manual analysis focuses on the current position and updates continuously as you navigate through the game.

5.6.1 Starting Manual Analysis

To start analyzing the current position:

1. Navigate to the position:
   Use the arrow keys or click moves in the Moves List to navigate to the position you want to analyze.
2. Switch to Manual Analysis tab:
   Navigate to the Manual Analysis tab in the Detail Panel (F3).
3. Start analysis:
   Use Manual Analysis → Start Manual Analysis (Alt+M / ⌥+M) to begin continuous analysis. The engine will analyze the current position and display principal variation lines with evaluations, depths, and move sequences.

Analysis continues automatically as you navigate to different positions in the game. To stop analysis, use the same menu item or keyboard shortcut again.

5.6.2 MultiPV Analysis

Manual Analysis supports MultiPV (Multiple Principal Variations), allowing you to see multiple candidate moves simultaneously. By default, analysis shows one principal variation line (PV1). You can add additional lines to compare different candidate moves:

• Add PV Line: Use Manual Analysis → Add PV Line (Alt+N / ⌥+N) to add another principal variation line. You can add as many lines as needed.
• Remove PV Line: Use Manual Analysis → Remove PV Line (Alt+R / ⌥+R) to remove the last added line (requires at least two lines).

Each PV line displays the engine's recommended move sequence, evaluation, search depth, and performance metrics. The first three PV lines (PV1, PV2, PV3) have color-coded indicators that match the colors of the corresponding arrows on the chessboard when enabled, helping you visually connect the analysis lines to the board arrows.

5.6.3 Exploring Variations

You can explore variations by hovering over moves in the PV lines:

• Miniature Board Preview: Enable Manual Analysis → Enable miniature preview to display a small board preview when hovering over moves in the PV lines. This shows the resulting position if that move were played.
• PV Arrows on Board: The PV1, PV2, and PV3 arrows on the chessboard (toggle with Alt+B / ⌥+B, Alt+2 / ⌥+2, Alt+3 / ⌥+3) show the recommended moves from each analysis line, making it easy to see candidate moves visually.

5.6.4 Positional Plan Exploration

Positional Plan Exploration visualizes how pieces move through the engine's recommended sequence, helping you understand strategic plans and piece coordination. Instead of just seeing individual moves, you can see complete piece trajectories—where pieces start, where they move, and the path they take through multiple moves.

To explore positional plans:

1. Enable plan exploration:
   Use Manual Analysis → Explore PV1 Positional Plans, Explore PV2 Positional Plans, or Explore PV3 Positional Plans to enable plan exploration for a specific PV line. Only one plan can be active at a time.
2. Configure exploration settings:
   Use Manual Analysis → Max number of pieces to explore to set how many pieces to track (1-3 pieces). The system automatically selects the pieces that move most frequently in the PV line. Use Manual Analysis → Max Exploration depth to set how many moves ahead to visualize (2-4 moves).

When enabled, the chessboard displays colored lines showing the trajectory of each tracked piece through the engine's recommended sequence. Each piece is assigned a distinct color that matches its indicator in the PV display, making it easy to follow piece movement patterns and understand positional themes.

5.7 Viewing Player Statistics

The Player Stats tab helps you see how a player tends to perform across many games: habits over time, typical accuracy, weak spots, played opening variants, and much more. Open it with View → Player Stats or F5.

The view refreshes automatically in the background if your chosen data source changes.

5.7.1 Prerequisites and data scope

Analyzed games. Only games that have been run through CARA’s game analysis are included. A player appears in the player list only if they have two or more analyzed games in the current source.

Source dropdown. Choose which pool of games to aggregate:

• None — empty view.
• Active Database — all games in the active database tab.
• All Open Databases — games from every open file tab.
• Selected games (Active Database) — only highlighted rows in the active tab; updates when your selection changes.
• Selected games (All Open Databases) — selected rows across all tabs.

Player dropdown. Each entry shows analyzed and total game counts (for example, “15 analyzed, 20 total”). Pick a player to display their statistics.

Dates in PGN. Some sections (activity heatmap, date-based progression charts) use the game dates stored in the PGN headers. If dates are missing or incomplete, those sections may be hidden and a short notice will be shown on the top of view.

5.7.2 Showing and hiding sections

The tab is built from independent sections (Overview, charts, trees, lists). Use the Player Stats menu to toggle each section on or off. As with most user settings, your choices will be persisted to your user settings file when you exit the application, so when you open the app again later they will remain exactly as you left them.

• Enable all turns on every section in one step.
• Disable all turns off every section in one step.
• Reset to defaults restores the application defaults, including which sections are visible and the detail options for those sections.

Several sections also offer context-menu settings when you right-click inside that section (for example chart colors or time grouping).

5.7.3 Overview

Purpose: Provide high-level, aggregated statistics for the selected player across the games included in the current computation—for example win rate, accuracy, average centipawn loss, estimated ELO rating, and move-classification totals.

Interactions: Right-click to copy this section or the full stats.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.4 Activity heatmap

Purpose: Aggregate analyzed games by calendar date and show the counts in a heatmap calendar so you can compare activity from day to day and see busy periods, gaps, and long quiet stretches at a glance.

Interactions: Double-click a day that has at least one game to open a Search Results tab listing those games. Hover a cell for the date and count.

Settings:

• Week starts on: Chooses whether calendar rows begin with Monday or Sunday.
• Color scale: Selects the color palette for cell shading: Green, Blue, or Amber.
• Intensity scale max: Sets how daily game counts map to the strongest color. Auto adapts the ceiling to your data; Fixed max uses a fixed ceiling, chosen under Fixed cap (games) as 3, 5, 8, 10, 15, or 20 games at full intensity.
• Partial PGN dates: Controls whether games without a complete PGN date are counted in the heatmap: Full dates only omits them, while Include partial-date stand-ins still counts them by assigning a stand-in calendar day when CARA can infer one from partial date information.
• Date range: Limits how much calendar time the heatmap covers: Trim to activity matches your data span, or a rolling Last ~12 months or Last ~24 months window.

5.7.5 Accuracy distribution

Purpose: Show a histogram of per-game accuracy for the selected player across the games in the current computation, so you can see how often games fall into each accuracy band (tight clusters, wide spread, or multiple peaks).

Interactions:

• Hover chart points to see bin ranges and counts.
• Right-click the section for Accuracy distribution settings; the same submenu is available from the Player Stats menu.

Settings:

• Accuracy scale: Chooses how accuracy is spaced along the horizontal axis. Linear keeps uniform spacing. High Accuracy Skew and Very High Accuracy Skew stretch the upper part of the range so more plot width goes to high-accuracy bins; use them when most games cluster in a narrow high band (often the case for very strong players, where per-game accuracy stays high) and you want neighboring high bands easier to tell apart. Very High Accuracy Skew pushes that effect further than High Accuracy Skew.
• Vertical axis: Uses Number of games or Share of games (%) as the Y-axis label (counts per bin vs percentage of games).
• Horizontal axis: Uses the full accuracy span Full range (0-100%) or zooms to Data range (first bin to last) so the plot width matches where your data actually sits.
• Bar count: Sets histogram resolution with Automatic, Fewer bars, or More bars.
• Colors: Selects the palette: Green, Blue, or Amber.
• Distribution line curve: Draws the distribution outline as Smooth or Straight segments.
• Distribution smoothing strength: When the curve is smooth, sets how strongly it is smoothed: 0.5, 1.0, 1.5, or 2.0 (higher values apply more smoothing).

5.7.6 Move accuracy

Purpose: Aggregates every classified move for the selected player across the games in the current computation and shows the overall mix as a pie chart with a percentage list: book moves, brilliancies, best and good moves, inaccuracies, mistakes, misses, and blunders (the same classification family as in Game Summary, but pooled across many games instead of one).

Interactions:

• Right-click in the section for Copy section to clipboard (this block only) or Copy stats to clipboard (full Player Stats text).
• Hover the chart to compare the selected player’s share against the opponents’ share for the same move classes.
• When the Player Stats detail area is narrow, the percentage list beside the pie may hide automatically so the chart keeps more width; widening the area brings the list back.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.7 Performance by phase

Purpose: Summarizes the selected player’s results in the three game phases—opening, middlegame, and endgame—across the games in the current computation. A horizontal bar chart shows average accuracy (%) per phase; beside it, a small table lists the same phases with average centipawn loss (CPL) so you can compare solid play vs typical cost of errors in each phase.

Interactions: Right-click in the section for Copy section to clipboard (this block only) or Copy stats to clipboard (full Player Stats text). Hover the bars to compare the selected player’s phase accuracy against opponents in the same phase.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.8 Avg. accuracy over game duration

Purpose: For the selected player and the games in the current computation, plots how running game accuracy (accuracy of all moves played so far in the game) typically changes as a game goes on. The horizontal axis is game progress from start to finish (0–100% of the game’s plies). For each progress step, CARA averages running accuracy across games for the player’s moves and, separately, across the same games for the opponent’s moves, then draws two lines: the player’s series and the opponents’ average series at the same progress. This answers “how does accuracy tend to evolve within a game?” and how the selected player’s accuracy over the game duration compares to their opponents.

Interactions:

• Move the mouse over the chart: a tooltip shows the interpolated game progress (%) together with the player’s accuracy (%) and the opponents’ average accuracy (%) at that progress.
• Right-click in the section for Copy section to clipboard (this block only) or Copy stats to clipboard (full Player Stats text). The section copy summarizes representative points along the curve as a small table.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.9 Accuracy progression

Purpose: For the selected player and the games in the current computation that have usable PGN game dates, buckets those games along the calendar (from the earliest to the latest dated game in the data). In each time bin CARA plots the median per-game accuracy so a few outliers do not dominate: a combined line plus separate lines for games played as White and as Black. The horizontal axis is real-world time.

Interactions:

• Move the mouse near the chart line: a tooltip shows the bin’s date range, median accuracy for the combined, White, and Black series, and how many games are in the bin.
• Right-click in the section for Copy section to clipboard, Copy stats to clipboard, and Time series settings (the same nested menu is under Player Stats on the menu bar).

Settings:

• Progression bins: Target number of time bins along the chart: 8, 12, 16, 24, or 32.
• Binning mode: Quantile (equal games per bin) splits the dated games into bins with similar counts (more detail when you played often); Equal calendar width uses similar calendar spans per bin.
• X axis layout: Uniform bins spaces bins evenly along the plot; Gap compressed squeezes long calendar gaps (with Max gap segment (calendar days) choosing 14, 28, 50, or 100); Calendar linear maps bin positions by real dates.
• Progression line style: Smooth or Straight segments.
• Smoothing strength (when the line is smooth): 0.5, 1.0, 1.5, or 2.0.

Show or hide this section from the Player Stats menu like other Player Stats blocks. The same Time series settings apply to Move quality progression and ACPL progression by phase; these charts share the time-series settings.

5.7.10 Move quality progression

Purpose: For the selected player, groups dated games from the current computation into the same calendar time bins as Accuracy progression (games need usable PGN dates). In each bin the chart shows the median per-game rate of best moves, top-three moves, and blunders—three percentage lines on the vertical axis.

Interactions:

• Move the mouse over the chart: a tooltip shows a date for the position under the cursor and an interpolated percentage for each visible series (matching the legend).
• Right-click in the section for Copy section to clipboard, Copy stats to clipboard, and Time series settings (the same nested menu is under Player Stats on the menu bar).

Settings: All Time series settings items (progression bins, binning mode, X axis layout, gap segment length, line style, smoothing strength) work the same way as for Accuracy progression; see that section for descriptions. Show or hide this section from the Player Stats menu like other Player Stats blocks.

5.7.11 ACPL progression by phase

Purpose: For the selected player, groups dated games from the current computation into the same calendar time bins as Accuracy progression (games need usable PGN dates). In each bin the chart shows the median per-game average centipawn loss (ACPL) separately for the opening, middlegame, and endgame—three lines on the vertical axis. Lower ACPL is better play in that phase.

Interactions:

• Move the mouse over the chart: a tooltip shows a date for the position under the cursor and an interpolated ACPL value for each phase line (Opening, Middlegame, Endgame), matching the legend.
• Right-click in the section for Copy section to clipboard, Copy stats to clipboard, and Time series settings (the same nested menu is under Player Stats on the menu bar).

Settings: All Time series settings items work the same way as for Accuracy progression; see that section for descriptions. Show or hide this section from the Player Stats menu like other Player Stats blocks.

5.7.12 Openings

Purpose: For the selected player and the games in the current computation, summarizes a few opening lines by ECO code and name. Up to three blocks appear when there is data: Most played (how many games reached each line), Worst accuracy (highest average CPL among openings with data), and Best accuracy (lowest average CPL). Each block is a small table with game counts; worst and best also show average CPL for that opening across the counted games.

Interactions:

• Right-click in the section for Copy section to clipboard (this block only) or Copy stats to clipboard (full Player Stats text).
• When the Player Stats detail area is narrow, long opening names in the middle column may be shortened with an ellipsis so ECO codes and numbers stay readable.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.13 Opening tree

Purpose: For the selected player and the games in the current computation, shows an expandable tree of opening variations reached. Each row is a branch for one SAN move; the ECO code and opening name are shown when available from the opening book, along with aggregated counts: total games, games as White and as Black, overall game accuracy (%), and accuracy in the opening phase only (%). Lines are arranged by opening family: continuations nest under their parent line, so related variations stay grouped and you can see how performance correlates along each branch. Together this gives repertoire shape beyond the flat Openings summary.

Interactions:

• Double-click a row to open a Search Results tab listing games where the player reached that move sequence (that branch).
• Click column headers to sort; the tree starts sorted by Total games (descending).
• Expand and collapse branches with the usual tree controls.
• Right-click in the section for Copy section to clipboard or Copy stats to clipboard. Section copy is a compact text summary of the tree through the first two moves, not the full depth. When the pointer is over the tree, the menu also offers Expand all and Collapse all.
• The + and − buttons beside the tree increase or decrease the tree’s vertical height (within configured limits).
• When the Player Stats area is narrow, some numeric columns may hide automatically so the move/opening column stays visible.

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.14 Endgame tree

Purpose: For the selected player and the games in the current computation, shows a two-level tree of classified endgames. Top-level rows are endgame groups (material-style families); expanding a group lists specific endgame types under it. Each row carries aggregated counts—total games, games as White and as Black—plus overall game accuracy (%) and accuracy in the endgame phase only (%), so you can compare whole-game results with performance after the position was classified as endgame. Groups and types are ordered by how many games fall into them (largest first). Together with Performance by phase, this helps you see which endgame categories the selected player reaches and how that player tends to score in them.

Interactions:

• Double-click a group row to open Search Results with every game that matches any type in that group; double-click a type row to open games for that single endgame type only.
• Click column headers to sort; the tree starts sorted by Total games (descending).
• Expand and collapse groups to show or hide the types underneath.
• Right-click in the section for Copy section to clipboard or Copy stats to clipboard (section copy uses the usual formatted Player Stats text for this section). When the pointer is over the tree, the menu also offers Expand all and Collapse all.
• The + and − buttons beside the tree increase or decrease the tree’s vertical height (within configured limits).
• When the Player Stats area is narrow, some numeric columns may hide automatically so the endgame type column stays readable (same pattern as the Opening tree).

Settings: None specific to this section beyond showing or hiding it through the Player Stats menu.

5.7.15 Games by performance

Purpose: Under the Games by Performance heading, the panel surfaces standout analyzed games for the selected player from the current Player Stats run. Best Games are the ones with the lowest average centipawn loss (CPL) for that player across the whole game; Worst Games are those with the highest average CPL. Each sub-row summarizes how many games qualify and the accuracy (%) range spanned by those picks. The worst list is built from games after reserving slots for the best list, so a game does not appear in both.

Interactions:

• Each row has a View button (for example View 3 → when three games qualify). Click it to open a Search Results tab with those games so you can open them from there.
• If no games qualify, the button stays disabled.
• Right-click in the section for Copy section to clipboard or Copy stats to clipboard. Section copy summarizes best and worst counts and accuracy ranges; in plain text that block is headed Top Games (the internal section name).
• When the Player Stats area is narrow, the View buttons may hide automatically so the description still fits—the same width behavior as Error patterns.

Settings: Show or hide this block with the Player Stats menu entry Games by performance. Caps on how many best and worst games are considered live under ui → panels → detail → player_stats → top_games in config.json (max_best and max_worst); see section 7.1 Customizing config.json.

5.7.16 Significant moves

Purpose: Under the Significant Moves heading, the panel highlights three move classes for the selected player across analyzed games in the current Player Stats run: Brilliant Moves, Misses, and Blunders (as recorded in stored analysis). Each row shows how many such moves occurred in aggregate and what share that is of the player’s total moves in those games; it also states how many individual instances are listed for the View action (capped by configuration). Together with Move accuracy, this gives both headline counts and a direct way to jump into concrete positions. Brilliant classifications depend on analysis settings—see Settings below.

Interactions:

• Each row has a View button (for example View 5 → when five moves are listed). Click it to open a Search Results tab with one row per move; the same game can appear more than once if it contains several qualifying moves.
• Search Results carries a Ref Ply for each row so opening the game can jump to that move; see section 4.4.2.
• Right-click in the section for Copy section to clipboard or Copy stats to clipboard.

Settings:

• Visibility: Player Stats → Significant moves.
• max_moves: In config.json, open ui → panels → detail → player_stats → significant_moves. The settings brilliant_moves, misses, and blunders can each set max_moves—the maximum number of moves that row’s View button will include when it opens Search Results (defaults are large). Details: section 7.1 Customizing config.json.
• Brilliant labels in analysis: Game Analysis → Brilliant Move Detection and related analysis options control brilliant move detection details.

5.7.17 Error patterns

Purpose: When Player Stats finds candidate issues for the selected player across the current analyzed games, this section lists them as separate cards. Each card has a short description, a severity color (for example critical vs moderate), and a frequency line (how often the pattern shows up and what share of relevant play that is). Rules cover several families of behavior—examples include blunders piling up in one phase, tactical misses, shaky opening error rates, persistently high centipawn loss, conversion or defensive trouble, and repeated slips in the same position.

Interactions:

• Each row has a View button. The label counts either matching games or individual occurrences (when the pattern tracks specific positions or moves), for example View 5 →.
• Click View to open a Search Results tab. When the pattern supplies reference plies, there is one result row per occurrence and Ref Ply tells the game view which move to jump to (see section 4.4.2). Otherwise you get one row per game and opening the game does not target a particular ply.
• Right-click in the section for Copy section to clipboard or Copy stats to clipboard (section copy uses the heading Error Patterns in plain text).
• When the Player Stats area is narrow, the View buttons hide and long descriptions are shortened so the cards still fit—similar to Games by performance.

Settings:

• Visibility: Player Stats → Error patterns.
• Detection thresholds: Under ui → panels → detail → player_stats → error_patterns → thresholds in config.json you can tune when each rule fires (phase blunder share, tactical miss counts, opening error rates, CPL and conversion heuristics, repeated-position minima, and similar). See section 7.1 Customizing config.json.

5.8 Adding Annotations

CARA annotations allow you to add custom markings to the chessboard, including text, arrows, circles, and square highlighting. Unlike regular PGN annotations, CARA annotations are not added to PGN notation as special encoded comments but are kept separate. Text can be freely positioned, sized, and rotated. Access the Annotations tab using View → Annotations or press F6.

5.8.1 Annotation Tools

The Annotations tab provides several tools for creating annotations:

• Text: Add free-form text annotations that can be positioned anywhere on the board. Text can be adjusted in size, rotated, and positioned relative to any square.
• Arrow: Draw arrows between squares to indicate move sequences or piece movements. Click and drag from one square to another to create an arrow.
• Circle: Add circular highlights around squares to emphasize specific squares.
• Square: Add square highlights to mark specific squares.
• Text: Add free-form text annotations that can be positioned anywhere on the board. Text can be adjusted in size, rotated, and positioned relative to any square.

All annotation types support customizable colors, size adjustments (0.5x to 2.0x), and optional shadow effects for better visibility. Select a tool from the toolbar, choose a color, and click on the chessboard to add annotations.

5.8.2 Annotation Preferences

You can customize the annotation color palette and text font settings using Annotations → Setup Preferences....

The dialog provides the following options:

• Color Palette: Customize the color palette used for annotations. Click any color swatch to open a color picker and select a new color.
• Text Annotation Font: Configure the font family and font size used for text annotations.
• Reset to Defaults: Click the "Reset to Defaults" button to restore the color palette and font settings to their default values.

Changes are saved to your user settings when you click "Save" and will persist across sessions.

5.8.3 Managing Annotations

Annotations are automatically attached to the current move (position) in the game. As you navigate through the game, annotations for each position are shown or hidden automatically.

You can manage annotations using the following options:

• Save Annotations: Use Annotations → Save Annotations to current game (Ctrl+Alt+S) to save all annotations to the active game. Annotations are compressed and stored in a PGN metadata tag, keeping the PGN move notation clean.
• Clear Move Annotations: Use Annotations → Clear all Annotations for current move (Ctrl+Alt+D) to remove all annotations for the current position.
• Clear All Annotations: Use Annotations → Clear all Annotations for current game (Ctrl+Shift+D / ⌘+Shift+D) to remove all annotations from the entire game.
• Highlight in Moves List: Use Annotations → Highlight annotated moves in moves list to highlight the White and Black move cells in the Moves List with the dominant annotation color for moves that have annotations, so you can quickly see which moves are annotated.
• Toggle Visibility: Use Board → Show Annotations (Alt+L / ⌥+L) to show or hide the annotation layer on the chessboard.

5.9 Copying and Moving Games

CARA provides practical copy, cut, and paste functionality that allows you to move games between databases, share games with other applications, and work with board positions. This section covers all clipboard operations for games and positions. You can also copy, cut, or paste selected games from the database table's right-click context menu (see section 4.4.3).

5.9.1 Copying Selected Games

To copy one or more games from a database to the clipboard:

1. Select games:
   In the Database Panel, select one or more games in the game table. You can select multiple games by holding Ctrl (individual selection) or Shift (range selection) while clicking.
2. Copy to clipboard:
   Use Edit → Copy selected Games (Ctrl+Shift+C / ⌘+Shift+C) to copy the selected games to your system clipboard as PGN text. The games remain in the source database.

The copied games are stored as standard PGN text, separated by double newlines. You can paste them into another database in CARA, or into any other application that accepts PGN text.

5.9.2 Cutting Selected Games

To move games from one database to another (or remove them from a database):

1. Select games:
   In the Database Panel, select one or more games in the game table.
2. Cut to clipboard:
   Use Edit → Cut selected Games (Ctrl+Shift+X) to copy the selected games to your system clipboard and remove them from the source database. If the active game is among the cut games, it will be cleared.

The cut games are stored as PGN text in your clipboard, ready to be pasted into another database. The source database is marked as having unsaved changes.

5.9.3 Pasting Games into a Database

To paste games from the clipboard into a database:

1. Ensure PGN is in clipboard:
   Make sure your system clipboard contains PGN text (either from copying/cutting games in CARA, or from another application).
2. Select destination database:
   Activate the database tab where you want to paste the games, or use the Clipboard database.
3. Paste games:
   Use Edit → Paste PGN to Clipboard DB (Ctrl+V / ⌘+V) to paste into the Clipboard database, or Edit → Paste PGN to active DB (Ctrl+Alt+V / ⌘+⌥+V) to paste into the currently active database.

All games in the clipboard PGN text are added to the selected database. If the clipboard contains multiple games, all are added, and the first game automatically becomes the active game. The destination database is marked as having unsaved changes.

5.9.4 Copying the Active Game PGN

To copy the currently active game's PGN to the clipboard:

1. Ensure a game is active:
   Make sure you have a game open and active (displayed in the main panel).
2. Copy PGN:
   Use Edit → Copy PGN (Ctrl+P / ⌘+P) to copy the active game's complete PGN text to your system clipboard.

This copies the full PGN notation of the active game, including all metadata tags, moves, comments, and variations. You can then paste it into another application or share it with others.

5.9.5 Copying and Pasting Board Positions

CARA also supports copying and pasting board positions using FEN (Forsyth-Edwards Notation):

• Copy FEN: Use Edit → Copy FEN (Shift+F) to copy the current board position as FEN notation to your system clipboard. This is useful for sharing specific positions or setting up positions in other chess applications.
• Paste FEN: Use Edit → Paste FEN to Board (Ctrl+F / ⌘+F) to paste a FEN position from your clipboard and update the chessboard to that position. When a FEN is pasted, the active game is cleared (set to None) since the board position is no longer part of a game sequence.

6.1 File Menu

6.1.1 Open PGN Database

Shortcut: Ctrl+O / ⌘+O

Opens one or more PGN files from your computer. Each file appears as a separate tab in the Database Panel.
See section 5.2.2 for detailed instructions.

6.1.2 Close PGN Database

Shortcut: Ctrl+W / ⌘+W

Closes the currently active database tab. Any unsaved changes will be lost if you haven't saved the database first.
See section 4.4.5 for more information.

6.1.3 Close All PGN Databases

Shortcut: Ctrl+Alt+W / ⌘+⌥+W

Closes all file-based database tabs. The Clipboard and Search Results tabs are preserved. Any unsaved changes will be lost if you haven't saved the databases first.
See section 4.4.5 for more information.

6.1.4 Clear Clipboard Database

Shortcut: Ctrl+Shift+C / ⌘+Shift+C

Removes all games from the Clipboard database.

6.1.5 Save PGN Database

Shortcut: Ctrl+S / ⌘+S

Saves the active database to disk, overwriting the existing file.
See section 4.4.5 for more information.

6.1.6 Save PGN Database as...

Shortcut: Ctrl+Shift+S / ⌘+Shift+S

Saves the active database to a new file location. This allows you to create a copy of the database without overwriting the original.
See section 4.4.5 for more information.

6.1.7 Import Games from Online...

Shortcut: Ctrl+Shift+I / ⌘+Shift+I

Opens a dialog to import games from Lichess or Chess.com.
See section 5.2.3 for detailed instructions.

6.1.8 Bulk Replace PGN header tags...

Shortcut: Ctrl+Shift+R / ⌘+Shift+R

Opens a dialog to find and replace text in metadata tags across multiple games.
See section 5.3.2 for detailed instructions.

6.1.9 Bulk Add/Remove PGN header tags...

Shortcut: Ctrl+Alt+T / ⌘+⌥+T

Opens a dialog to add or remove metadata tags across multiple games.
See section 5.3.3 for detailed instructions.

6.1.10 Bulk Clean PGN...

Shortcut: Ctrl+Shift+L / ⌘+Shift+L

Opens a dialog to remove unwanted elements (comments, variations, annotations, etc.) from PGN notation across multiple games.
See section 5.3.4 for detailed instructions.

6.1.11 Deduplicate Games in Active Database...

Shortcut: Ctrl+Shift+U / ⌘+Shift+U

Opens a dialog to identify and remove duplicate games from the active database.
See section 5.3.5 for detailed instructions.

6.1.12 Search Games...

Shortcut: Ctrl+Shift+F / ⌘+Shift+F

Opens a dialog to search for games across databases using multiple criteria and logical operators.
See section 5.4 for detailed instructions.

6.1.13 Close Search Results

Shortcut: Ctrl+Shift+W / ⌘+Shift+W

Closes the Search Results tab in the Database Panel. This menu item is only enabled when a search results tab is open.

6.1.14 Close Application

Shortcut: Ctrl+Q / ⌘+Q

Closes the CARA application. Any unsaved changes in open databases will be lost if you haven't saved them first.

6.2 Edit Menu

6.2.1 Copy FEN

Shortcut: Shift+F

Copies the current board position as FEN (Forsyth-Edwards Notation) to your system clipboard.
See section 5.9.5 for more information.

6.2.2 Copy PGN

Shortcut: Ctrl+P / ⌘+P

Copies the currently active game's complete PGN text to your system clipboard.
See section 5.9.4 for more information.

6.2.3 Copy selected Games

Shortcut: Ctrl+Shift+C / ⌘+Shift+C

Copies the selected games from the active database to your system clipboard as PGN text. The games remain in the source database.
See section 5.9.1 for more information.

6.2.4 Cut selected Games

Shortcut: Ctrl+Shift+X

Copies the selected games to your system clipboard and removes them from the source database.
See section 5.9.2 for more information.

6.2.5 Paste FEN to Board

Shortcut: Ctrl+F / ⌘+F

Pastes a FEN position from your clipboard and updates the chessboard to that position. The active game is cleared when a FEN is pasted.
See section 5.9.5 for more information.

6.2.6 Paste PGN to Clipboard DB

Shortcut: Ctrl+V / ⌘+V

Pastes PGN text from your system clipboard into the Clipboard database. All games in the clipboard are added, and the first game becomes active.
See section 5.2.1 and section 5.9.3 for more information.

6.2.7 Paste PGN to active DB

Shortcut: Ctrl+Alt+V / ⌘+⌥+V

Pastes PGN text from your system clipboard into the currently active database. All games in the clipboard are added, and the first game becomes active.
See section 5.2.1 and section 5.9.3 for more information.

6.3 Board Menu

6.3.1 Rotate Board

Shortcut: X

Toggles the board orientation, rotating it 180 degrees. This is useful for viewing positions from the opposite side's perspective.

6.3.2 Show Game Info

Shortcut: Alt+I / ⌥+I

Toggles the display of game information (players, result, date, etc.) above the chessboard.

6.3.3 Show Coordinates

Shortcut: Alt+C / ⌥+C

Toggles the display of coordinate labels (a-h, 1-8) around the chessboard edges.

6.3.4 Show Turn Indicator

Shortcut: Alt+T / ⌥+T

Toggles the display of the turn indicator showing which side is to move.
See section 4.3.6 for more information.

6.3.5 Show Material

Shortcut: Alt+U / ⌥+U

Toggles the display of the material widget showing captured pieces and material difference.
See section 4.3.4 for more information.

6.3.6 Show Game Tags

Shortcut: Alt+G

Toggles the visibility of the Game Tags widget next to the chessboard.

6.3.7 Show Evaluation Bar

Shortcut: Alt+E / ⌥+E

Toggles the display of the evaluation bar showing the engine's assessment of the current position.
See section 4.3.3 for more information.

6.3.8 Show Positional Heat-map

Shortcut: Alt+H / ⌥+H

Toggles the display of the positional heatmap overlay showing positional factors through color-coded gradients.
See section 4.3.7 for detailed information.

6.3.9 Show Played Move

Shortcut: Alt+P / ⌥+P

Toggles the display of an arrow on the chessboard indicating the last move played in the game.

6.3.10 Show Best Next Move

Shortcut: Alt+B / ⌥+B

Toggles the display of an arrow showing the engine's best recommended move (PV1) from manual analysis.

6.3.11 Show Next Best Move (PV2)

Shortcut: Alt+2 / ⌥+2

Toggles the display of an arrow showing the engine's second-best recommended move (PV2) from manual analysis.

6.3.12 Show Next Best Move (PV3)

Shortcut: Alt+3 / ⌥+3

Toggles the display of an arrow showing the engine's third-best recommended move (PV3) from manual analysis.

6.3.13 Show Best Alternative Move

Shortcut: Alt+A / ⌥+A

Toggles the display of an arrow showing the best alternative move found during game analysis (the move that should have been played instead of the actual move).

6.3.14 Show Move Classification Icons

Shortcut: Alt+4 / ⌥+4

Toggles small badges on the played move's destination square that show the move assessment (e.g. book move, best move, good move, brilliant, inaccuracy, mistake, miss, blunder). Available once the game has been analyzed.

6.3.15 Show Annotations Layer

Shortcut: Alt+L / ⌥+L

Toggles the visibility of the annotations layer on the chessboard, showing or hiding all custom annotations (text, arrows, circles, squares).
See section 5.8 for more information.

6.3.16 Path trajectory style

Selects the visual style for piece trajectory lines displayed during positional plan exploration:

• Straight: Trajectory lines are drawn as straight segments between squares.
• Bezier: Trajectory lines are drawn as smooth Bezier curves connecting squares.

6.4 Game tags menu

The Game tags menu provides actions for working with game tags on the currently active game.

After the top items (Manage game tags… and Clear all game tags), the menu lists your predefined tags (only those you have left visible) and your custom tags as checkable entries so you can turn each one on or off for the active game (see section 6.4.3). The same choices appear when you right-click the Game Tags widget.

6.4.1 Manage game tags…

Opens the Manage game tags dialog. The dialog has two areas:

• Built-in game tags — Shows every predefined tag (names and colors come from the application configuration). You cannot rename or remove these tags. Hover a chip to show a color control (change how the tag appears wherever game tags are shown) and a visibility control (eye / eye-off) to hide or show that tag in the tag picker. Hidden built-ins still appear in this dialog so you can turn them back on.
• Custom game tags — Lists tags you have defined yourself. Use the + chip to add a tag (name and color). Hover an existing custom chip for color and remove.

At the bottom, Reset to Defaults clears your overrides for built-in tags only (colors and hide/show state); it does not delete custom tag definitions. OK saves changes; Cancel discards changes made in this session. Built-in and custom choices you save are stored with your user preferences.

6.4.2 Clear all game tags

Removes all game tags from the currently active game in one step (the full tag list stored on that game). This still applies if some assigned tags no longer appear in the menu because their built-in definition is hidden—you may use this to clean up those assignments even though you cannot toggle them individually from the menu until you show the tag again in Game tags → Manage game tags….

6.4.3 Tag toggles in the menu and widget

After Manage game tags…, a separator, and Clear all game tags, the menu lists every visible tag definition: built-in tags first, then a separator and your custom tags (if any). Each entry is checkable and turns the corresponding tag on or off for the active game only.

Built-in tag definitions you have marked hidden in Manage game tags… are not listed here (and not in the widget’s context menu), so you cannot assign or remove them from the pick list until you show them again. They may still be stored on the game from earlier; use Clear all game tags if you want to remove every tag at once.

If the active game contains a tag name that is not part of your current definitions (for example text imported from elsewhere), those names appear under Unmanaged game tags (this game) so you can still toggle them off.

6.5 PGN Menu

6.5.1 Show PGN header tags

Shortcut: Ctrl+M / ⌘+M

Toggles the display of PGN header tags (Event, Site, Date, etc.) in the PGN Notation Pane.
See section 4.5 for more information.

6.5.2 Show Comments

Shortcut: Ctrl+Shift+M / ⌘+Shift+M

Toggles the display of move comments in the PGN Notation Pane.
See section 4.5 for more information.

6.5.3 Show Variations

Shortcut: Ctrl+Shift+V / ⌘+Shift+V

Toggles the display of move variations in the PGN Notation Pane.
See section 4.5 for more information.

6.5.4 Show Non-Standard Tags

Shortcut: Ctrl+Shift+T / ⌘+Shift+T

Toggles the display of non-standard tags like [%evp] and [%mdl] within comments in the PGN Notation Pane.
See section 4.5 for more information.

6.5.5 Show Annotations

Shortcut: Ctrl+Shift+A / ⌘+Shift+A

Toggles the display of move annotations (symbols like !, ?, and NAGs) in the PGN Notation Pane.
See section 4.5 for more information.

6.5.6 Show Results

Shortcut: Ctrl+R / ⌘+R

Toggles the display of game results (1-0, 0-1, 1/2-1/2) in the PGN Notation Pane.
See section 4.5 for more information.

6.5.7 Display NAG move assessments as...

This submenu allows you to choose how NAG (Numeric Annotation Glyph) move assessments are displayed in the PGN Notation Pane:

• Symbols (??, ?, ?! ..): Displays common NAGs as symbols (!, !!, ?, ??, !?, ?!) and other NAGs as numbers
• Text: Displays all NAGs as readable text descriptions in parentheses (e.g., "good move", "poor move", "White has a slight advantage")

The selected option is saved in your user settings and persists between application sessions.
See section 4.5 for more information.

6.5.8 Remove Comments

Permanently removes all comments from the active game's PGN notation. This action modifies the game's actual PGN content and cannot be undone. The game will be marked to contain unsaved changes and the changes will be persisted when you save the database.
See section 4.5 for more information.

6.5.9 Remove Variations

Permanently removes all move variations from the active game's PGN notation. This action modifies the game's actual PGN content and cannot be undone. The game will be marked to contain unsaved changes and the changes will be persisted when you save the database.
See section 4.5 for more information.

6.5.10 Remove Non-Standard Tags

Permanently removes non-standard tags (like [%evp] and [%mdl]) from comments in the active game's PGN. This action modifies the game's actual PGN content and cannot be undone. The game will be marked to contain unsaved changes and the changes will be persisted when you save the database.
See section 4.5 for more information.

6.5.11 Remove Annotations

Permanently removes all move annotations (symbols and NAGs) from the active game's PGN notation. This action modifies the game's actual PGN content and cannot be undone. The game will be marked to contain unsaved changes and the changes will be persisted when you save the database.
See section 4.5 for more information.

6.6 Moves List Menu

6.6.1 Column Profiles

The Moves List menu displays all available column profiles at the top. Each profile is a named configuration that defines which columns are visible and their order. Switch between profiles by selecting them from the menu or using number keys 1 through 9 (assigned to the first nine profiles).
See section 4.5.1 for detailed information about column profiles and default profiles.

6.6.2 Save Profile

Shortcut: Ctrl+Shift+P / ⌘+Shift+P

Saves the current column profile, overwriting the existing profile with the current column visibility, order, and width settings.
See section 4.5.1 for more information.

6.6.3 Save Profile as...

Shortcut: Ctrl+Alt+P / ⌘+⌥+P

Creates a new column profile with a custom name, using the current column visibility, order, and width settings. The new profile is then accessible via the Moves List menu and is assigned a keyboard shortcut (1-9) based on its position in the profile list.
See section 4.5.1 for more information.

6.6.4 Remove Profile

Shortcut: Ctrl+Shift+Delete / ⌘+Shift+Delete

Permanently removes the currently active column profile.

6.6.5 Setup Profile...

Opens a dialog for configuring all column settings at once, including column visibility, order, and widths. This provides a convenient way to manage multiple columns simultaneously rather than toggling them individually.
See section 4.5.1 for more information.

6.6.6 Column Visibility

The Moves List menu includes submenus organized by column category for toggling individual column visibility:

• Basic Columns: Move number, White moves, Black moves, Comments
• Evaluation Columns: White/Black evaluations, CPL values (including top-2 and top-3 alternatives)
• Best Moves Columns: Best move alternatives for White/Black (including top-2 and top-3), Top-3 move indicators
• Analysis Columns: Move assessments (Brilliant, Best Move, Inaccuracy, etc.), Engine depth
• Material Columns: Captured pieces, Material counts
• Position Columns: ECO codes, Opening names, FEN positions

Toggle any column's visibility by selecting it from the appropriate submenu. Changes are applied immediately but are not persisted until you save the profile.
See section 4.5.1 for more information.

6.7 Game Analysis Menu

6.7.1 Start Game Analysis

Shortcut: Ctrl+G / ⌘+G

Initiates automatic analysis of the currently active game using the engine assigned to the Game Analysis task. The engine analyzes each move in the game, providing evaluations, move classifications, and best move alternatives.
See section 5.5 for detailed instructions.

6.7.2 Cancel Game Analysis

Shortcut: Escape

Cancels an ongoing game analysis. This menu item is only enabled while analysis is in progress. When cancelled, analysis stops and any moves already analyzed remain in the Moves List. You can resume analysis later from where it left off.
See section 5.5.6 for more information.

6.7.3 Bulk Analyze Database...

Opens a dialog to analyze multiple games at once. CARA automatically optimizes available CPU cores to analyze multiple games in parallel, maximizing analysis speed. Progress and estimated time remaining are displayed in the status bar, and you can cancel and resume bulk analysis at any time.
See section 5.5.7 for detailed instructions.

6.7.4 Configure Classification Settings...

Shortcut: Ctrl+Shift+K / ⌘+Shift+K

Opens a dialog to customize the thresholds used for move classification (Brilliant, Best Move, Good Move, Inaccuracy, Mistake, Blunder). These thresholds determine how moves are categorized based on Centipawn Loss (CPL) values. The dialog also includes settings for brilliancy detection, including shallow depth ranges, minimum agreement requirements, and candidate move selection. See section 5.5.2 for more information about move classifications and section 5.5.3 for details on brilliancy detection.

6.7.5 Normalized Evaluation Graph

Shortcut: Ctrl+Shift+N / ⌘+Shift+N

Toggles the normalized evaluation graph display mode in the Moves List. When enabled, evaluation values are normalized to a scale that better highlights relative evaluation changes throughout the game, making it easier to identify critical moments and evaluation swings.

6.7.6 Brilliant Move Detection

Toggles whether CARA performs brilliancy detection after initial game analysis. When enabled, CARA analyzes candidate moves at shallow engine depths to identify exceptional moves that appear suboptimal at shallow depths but are actually strong when analyzed more deeply. This detection step runs automatically after the main analysis completes. See section 5.5.3 for a detailed explanation of how brilliancy detection works.

6.7.7 Auto Tag Games

Toggles whether CARA performs auto-tagging after analysis completes. When enabled, CARA may assign game tags according to the rules described in section 5.5.5 and the tags you allow under Select Tags for Auto-Tagging (see section 6.7.8). When disabled, no automatic game tags are applied by this feature.

6.7.8 Select Tags for Auto-Tagging

Opens a submenu with a checkable entry for each supported auto-tag (see the table in section 5.5.5). Only checked tags can be added or refreshed by auto-tagging; unchecked rules are skipped. Your selection is saved with your user preferences. This submenu is disabled while Auto Tag Games is turned off.

6.7.9 Return to PLY 0 after analysis completes

Toggles whether CARA automatically navigates to the starting position (PLY 0) when analysis completes. When enabled, the board and Moves List automatically return to PLY 0 after analysis finishes.

6.7.10 Switch to Moves List at the start of Analysis

Toggles whether CARA automatically switches to the Moves List tab when analysis begins. This is enabled by default, ensuring you can immediately see analysis results as they are generated.

6.7.11 Switch to Game Summary after Analysis

Toggles whether CARA automatically switches to the Game Summary tab when analysis completes. When enabled, you are taken directly to the condensed overview of key game moments and statistics after analysis finishes.

6.7.12 Store Analysis results in PGN Tag

Toggles whether analysis results (evaluations, CPL values, move classifications) are saved in a PGN metadata tag for persistence across sessions. When enabled, analysis data is serialized and stored in the game's PGN, allowing you to preserve analysis results even after closing and reopening the database.

6.8 Manual Analysis Menu

6.8.1 Start Manual Analysis

Shortcut: Alt+M / ⌥+M

Starts or stops continuous engine analysis of the current position. When enabled, the engine analyzes the current position and displays principal variation lines with evaluations, depths, and move sequences. Analysis continues automatically as you navigate to different positions. Use the same menu item or shortcut again to stop analysis.
See section 5.6.1 for detailed instructions.

6.8.2 Add PV Line

Shortcut: Alt+N / ⌥+N

Adds an additional principal variation line to the MultiPV analysis display. This allows you to compare multiple candidate moves simultaneously. You can add as many lines as needed.
See section 5.6.2 for more information.

6.8.3 Remove PV Line

Shortcut: Alt+R / ⌥+R

Removes the last added principal variation line from the MultiPV analysis display.
See section 5.6.2 for more information.

6.8.4 Enable miniature preview

Toggles the miniature board preview feature. When enabled, hovering over moves in any PV line displays a small chessboard preview showing the position after that move. This helps you quickly visualize the resulting position.
See section 5.6.3 for more information.

6.8.5 Explore PV1 Positional Plans

Toggles positional plan exploration for the first principal variation line. When enabled, the chessboard displays colored trajectory lines showing how pieces move through the engine's recommended sequence. Only one plan can be active at a time.
See section 5.6.4 for detailed instructions.

6.8.6 Explore PV2 Positional Plans

Toggles positional plan exploration for the second principal variation line. When enabled, the chessboard displays colored trajectory lines showing how pieces move through the engine's recommended sequence. Only one plan can be active at a time.
See section 5.6.4 for detailed instructions.

6.8.7 Explore PV3 Positional Plans

Toggles positional plan exploration for the third principal variation line. When enabled, the chessboard displays colored trajectory lines showing how pieces move through the engine's recommended sequence. Only one plan can be active at a time.
See section 5.6.4 for detailed instructions.

6.8.8 Max number of pieces to explore

Sets how many pieces to track in the positional plan exploration visualization. Options are 1, 2, or 3 pieces. The system automatically selects the pieces that move most frequently in the active PV line up to this limit. Each tracked piece is assigned a distinct color and displayed with trajectory lines on the chessboard.
See section 5.6.4 for more information.

6.8.9 Max Exploration depth

Sets the exploration depth for piece trajectories in positional plan exploration. Options are 2, 3, or 4 moves ahead. This determines how many moves into the future the trajectory visualization extends, showing the complete path each piece takes through the engine's recommended sequence.
See section 5.6.4 for more information.

6.8.10 Hide other arrows during plan exploration

Toggles whether other board arrows (played move, best alternative move, PV arrows) are hidden when positional plan exploration is active. When enabled, only the piece trajectory lines are displayed, providing a cleaner view focused on the positional plan visualization.

6.9 Player Stats Menu

The Player Stats menu on the menu bar controls the Player Stats tab in the detail panel: which sections are visible and several chart-specific options. The same nested settings also appear when you right-click inside the matching section on the tab. For what each block shows and how to use it, see section 5.7 Viewing Player Statistics.

6.9.1 Reset to defaults

Restores Player Stats options to the application template values after confirmation: section visibility, Activity heatmap settings, Accuracy distribution settings, and Time series settings (bins, binning mode, axis layout, gap segments, line style, smoothing, and related choices).

6.9.2 Enable all and Disable all

Enable all and Disable all turn every section’s visibility on or off together, so you can quickly show the full page or clear it and then turn individual sections back on—handy when you want a simpler layout without flipping each toggle option one by one. They only update those section visibility toggles; they do not change the saved options inside Activity heatmap settings, Accuracy distribution settings, or Time series settings.

6.9.3 Per-section visibility and detail settings

The remaining entries are toggle options for each Player Stats section (on means the section is shown on the tab). Three submenus supply extra display options where they apply: Activity heatmap settings, Accuracy distribution settings, and Time series settings (for the date-based progression charts). What each section shows is described in section 5.7 Viewing Player Statistics.

6.10 Annotations Menu

6.10.1 Clear all Annotations for current game

Shortcut: Ctrl+Shift+D / ⌘+Shift+D

Removes all annotations from the entire active game. This action affects all positions in the game and cannot be undone.
See section 5.8.3 for more information.

6.10.2 Clear all Annotations for current move

Shortcut: Ctrl+Alt+D

Removes all annotations for the current position (move) in the game. Annotations for other positions remain unchanged.
See section 5.8.3 for more information.

6.10.3 Save Annotations to current game

Shortcut: Ctrl+Alt+S

Saves all annotations to the active game by serializing them into a PGN metadata tag. Annotations are compressed and stored separately from the PGN move notation, keeping the PGN clean. This marks the game as modified, and annotations will be persisted when you save the database.
See section 5.8.3 for more information.

6.10.4 Highlight annotated moves in moves list

When checked, moves that have annotations are highlighted in the Moves List: the White and Black move columns (algebraic notation) use the dominant color from the annotations for that move as a background, with contrasting text so the move remains readable. This makes it easy to see at a glance which moves in the game have annotations. The setting is saved in your user preferences.

6.10.5 Setup Preferences...

Opens the Annotation Preferences dialog for customizing the annotation color palette and text font settings. Changes are saved to your user settings and persist across sessions.
See section 5.8.2 for detailed instructions.

6.11 Engines Menu

6.11.1 Add Engine...

Shortcut: Ctrl+E

Opens a dialog to add a new UCI-compatible chess engine to CARA. You can browse for the engine executable file, and CARA will automatically validate that it supports the UCI protocol. The first engine you add is automatically assigned to all analysis tasks.
See section 5.1.1 for detailed instructions.

6.11.2 Engine Submenus

For each configured engine, a submenu is displayed with the engine's name. Each submenu provides the following options:

• Remove Engine: Permanently removes the engine from CARA. If the engine is currently assigned to any tasks, those assignments are cleared. CARA automatically ensures that at least one engine is always assigned to each analysis task.
• Engine Configuration: Opens the engine configuration dialog with a tab for each task (Evaluation, Game Analysis, Manual Analysis, Brilliancy Detection), where you can set thread count, depth limits, time limits, and engine-specific options per task.
  See section 5.1.2 for more information.
• Set for all tasks: Assigns this engine to all four analysis tasks at once (game analysis, evaluation, manual analysis, and brilliancy detection).
• Set as Game Analysis Engine: Assigns the engine to the game analysis task.
• Set as Evaluation Engine: Assigns the engine to the evaluation task (used for the evaluation bar).
• Set as Manual Analysis Engine: Assigns the engine to the manual analysis task.
• Set as Brilliancy Detection Engine: Assigns the engine to the brilliancy detection task (used when brilliancy detection is enabled after game analysis).

Only one engine can be assigned to each task at a time.
See section 5.1.2 for more information about task assignment.

6.12 AI Summary Menu

6.12.1 AI Model Settings...

Opens a dialog for configuring AI model settings. CARA supports three options: OpenAI, Anthropic, and Custom endpoint (e.g. a local LLM). You must configure at least one provider and select a model before using the AI Summary feature. For custom endpoints, set the base URL (and optionally an API key) and choose a model; see section 7.9.

To acquire API keys for cloud providers:

• OpenAI: Sign up at platform.openai.com and create an API key in your account settings. Visit platform.openai.com/api-keys to manage your keys.
• Anthropic: Sign up at console.anthropic.com and create an API key in your account settings. Visit console.anthropic.com/settings/keys to manage your keys.

For a custom endpoint, an API key is optional (e.g. leave empty for local servers).

6.12.2 Use OpenAI Models

Toggles whether to use OpenAI models for AI Summary. When enabled, OpenAI models are available for selection. This option is mutually exclusive with "Use Anthropic Models" and "Use Custom Endpoint"—only one provider can be active at a time.

6.12.3 Use Anthropic Models

Toggles whether to use Anthropic models for AI Summary. When enabled, Anthropic models are available for selection. This option is mutually exclusive with "Use OpenAI Models" and "Use Custom Endpoint"—only one provider can be active at a time.

6.12.4 Use Custom Endpoint

Toggles whether to use the custom endpoint (e.g. local LLM) for AI Summary. When enabled, models from the configured custom base URL are available. This option is mutually exclusive with "Use OpenAI Models" and "Use Anthropic Models"—only one provider can be active at a time.

6.12.5 Include Game Analysis Data in Pre-Prompt

Toggles whether game analysis data (evaluations, move classifications, CPL values, best move alternatives) is included in the pre-prompt sent to the AI model. When enabled, the AI has access to detailed engine analysis, enabling more accurate assessments of moves and positions.

6.12.6 Include PGN header tags in pre-prompt

Toggles whether PGN header tags (player names, ELO ratings, event information, etc.) are included in the pre-prompt sent to the AI model. When enabled, the AI has access to this PGN header context, providing more informed responses.

6.13 Notes Menu

The Notes menu provides actions for managing game notes stored in the current game's PGN (CARANotes tag).

6.13.1 Clear Notes for current game

Removes the notes from the current game in memory (clears the CARANotes tag). Shortcut: Ctrl+Shift+E.

6.13.2 Save Notes to current game

Saves the text from the Notes tab into the current game's PGN as a CARANotes tag (in memory). The database is marked as having unsaved changes until you save the database. Shortcut: Ctrl+Alt+N.

6.14 Help Menu

6.14.1 Open Manual

Opens the application manual in your default web browser, providing comprehensive documentation and instructions for using CARA.

6.14.2 Watch Video Tutorials

Opens the CARA Chess YouTube channel in your default web browser, where you can watch video tutorials for using CARA.

6.14.3 Visit GitHub Repository

Opens the CARA project repository on GitHub in your default web browser, where you can view the source code, report issues, or contribute to the project.

6.14.4 Check for Updates...

Checks if a newer version of CARA is available.

6.14.5 About...

Opens the About dialog displaying application information, including the application name, version number, description, and copyright information. The dialog provides a quick reference for identifying the CARA version you are using.

6.15 Complete Keyboard Shortcuts

This section provides a comprehensive reference of all keyboard shortcuts in CARA.

6.15.1 Game Navigation

Essential shortcuts for navigating through games:

• Right Arrow: Navigate to next move
• Left Arrow: Navigate to previous move

6.15.2 Detail Panel Tabs

Quick access to different analysis views:

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

6.15.3 Game Analysis

Shortcuts for analyzing games:

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

6.15.4 File Operations

Standard file management shortcuts:

• 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

6.15.5 Importing and Opening Games

Shortcuts for importing and opening games:

• Ctrl+V / ⌘+V: Paste PGN to Clipboard database
• Ctrl+Alt+V / ⌘+⌥+V: Paste PGN to active database
• Ctrl+Shift+I / ⌘+Shift+I: Import games from online platforms

6.15.6 Copy and Cut Operations

Shortcuts for copying and moving game data:

• Ctrl+P / ⌘+P: Copy active game PGN to clipboard
• Shift+F: Copy current board position (FEN) to clipboard
• Ctrl+F / ⌘+F: Paste FEN position to board
• Ctrl+Shift+C / ⌘+Shift+C: Copy selected games to clipboard
• Ctrl+Shift+X: Cut selected games to clipboard

6.15.7 Moves List Column Profiles

Shortcuts for managing and switching column 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

6.15.8 Board Display Options

Shortcuts for toggling board display elements:

• X: Rotate board 180 degrees
• Alt+C / ⌥+C: Toggle coordinates display
• Alt+T / ⌥+T: Toggle turn indicator
• Alt+I / ⌥+I: Toggle game information display
• Alt+E / ⌥+E: Toggle evaluation bar
• Alt+U / ⌥+U: Toggle material widget
• Alt+G: Toggle Game Tags widget
• Alt+H / ⌥+H: Toggle positional heatmap
• 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+4 / ⌥+4: Toggle move classification icons
• Alt+L / ⌥+L: Toggle annotations layer

6.15.9 Manual Analysis

Shortcuts for manual position analysis:

• Alt+M / ⌥+M: Start or stop continuous engine analysis
• Alt+N / ⌥+N: Add principal variation line
• Alt+R / ⌥+R: Remove principal variation line

6.15.10 Annotations

Shortcuts for managing annotations:

• Ctrl+Alt+S: Save annotations to current game
• Ctrl+Alt+D: Clear all annotations for current move
• Ctrl+Shift+D / ⌘+Shift+D: Clear all annotations for current game

6.15.11 Engine Management

Shortcuts for managing chess engines:

• Ctrl+E: Add engine

6.15.12 Database Operations

Shortcuts for database management and bulk operations:

• Ctrl+Shift+F / ⌘+Shift+F: Search games across databases
• Ctrl+Shift+W / ⌘+Shift+W: Close search results tab
• Ctrl+Shift+R / ⌘+Shift+R: Bulk replace tags
• Ctrl+Alt+T / ⌘+⌥+T: Bulk add/remove tags
• Ctrl+Shift+L / ⌘+Shift+L: Bulk clean PGN
• Ctrl+Shift+U / ⌘+Shift+U: Deduplicate games
• Ctrl+Shift+C / ⌘+Shift+C: Clear Clipboard database

6.15.13 PGN Display Options

Shortcuts for controlling PGN notation display:

• 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

6.15.14 Notes

Shortcuts for game notes:

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

7.1 Customizing config.json

The config.json file controls all UI styling, layout dimensions, colors, fonts, and application-wide default settings. While the file is read-only from the application's perspective, you can manually edit it to customize CARA's appearance without modifying any source code.

7.1.1 File Structure

The config.json file is located in the app/config/ directory and uses a hierarchical JSON structure. Colors are specified as RGB arrays with values from 0 to 255 (e.g., [217, 217, 217] for light gray). Font sizes are specified in points, and dimensions are in pixels.

7.1.2 Example: Changing Chessboard Square Colors

To change the colors of the chessboard squares:

1. Locate the squares configuration:
   Open config.json in a text editor and navigate to: ui → panels → main → board → squares
2. Modify the color values:
   You'll find two color properties:
   • "light_color": [217, 217, 217] - Color for light squares (default: light gray)
   • "dark_color": [58, 117, 196] - Color for dark squares (default: blue)
   Change these RGB arrays to your desired colors. For example, to use a classic green and cream color scheme:

   "squares": {
       "light_color": [240, 217, 181],
       "dark_color": [181, 136, 99]
   }

3. Save and restart:
   Save the file and restart CARA for the changes to take effect. If the JSON syntax is invalid, CARA will display an error message and may fail to start.

7.1.3 Other Common Customizations

You can customize many other visual elements in config.json:

• Arrow colors: Modify colors for played move, best move, PV arrows, and best alternative move arrows in ui → panels → main → board
• Font families and sizes: Change fonts throughout the application in various font_family and font_size properties
• Dialog dimensions: Adjust dialog widths and heights in ui → dialogs
• Panel colors: Modify background colors, borders, and text colors in ui → panels
• Move classification colors: Customize colors for move classifications (Brilliant, Best Move, Inaccuracy, etc.) in ui → panels → detail → moveslist → colors

7.1.4 Configuring PGN Export Format

CARA allows you to customize how PGN files are formatted when saving databases. The PGN export settings control whether move notation is wrapped at a fixed width or saved as a single line.

To configure PGN export formatting:

1. Locate the PGN export configuration:
   Open config.json in a text editor and navigate to: pgn → export
2. Modify the export settings:
   You'll find two properties:
   • "use_fixed_width": true - When true, move notation is wrapped at the specified width. When false, move notation is saved as a single continuous line.
   • "fixed_width": 80 - The character width limit when use_fixed_width is true. Default is 80 characters, which is a common standard for PGN files.
   Example configuration:

   "pgn": {
       "export": {
           "use_fixed_width": true,
           "fixed_width": 80
       }
   }

3. Save and restart:
   Save the file and restart CARA for the changes to take effect. The new formatting will apply to all future save operations (both "Save" and "Save As").

7.1.5 Configuring PGN Import Settings

CARA allows you to configure how PGN files are processed when importing games. The PGN import settings control character handling during file loading.

To configure PGN import settings:

1. Locate the PGN import configuration:
   Open config.json in a text editor and navigate to: pgn → import
2. Modify the import settings:
   You'll find the following property:
   • "strip_pua_characters": true - When true, removes Unicode Private Use Area (PUA) characters (U+E000-U+F8FF) from PGN text during import. These characters are used by ChessBase and other chess software for special font symbols. When fonts don't support these characters, they appear as blue boxes or other visual artifacts. Setting this to true removes them automatically during import to ensure clean PGN text.
   Example configuration:

   "pgn": {
       "import": {
           "strip_pua_characters": true
       }
   }

3. Save and restart:
   Save the file and restart CARA for the changes to take effect. The new settings will apply to all future import operations (opening PGN files, pasting PGN text, importing from online platforms).

7.1.6 Customizing PGN Display Formatting

CARA allows you to customize the visual appearance of PGN notation in the Detail Panel, including colors, fonts, and how annotations and NAGs are displayed.

Note: The display format for NAG move assessments (symbols vs. text) can be changed via the PGN menu (Display NAG move assessments as...) and is not configured through config.json.

To customize PGN display formatting:

1. Locate the PGN formatting configuration:
   Open config.json in a text editor and navigate to: ui → panels → detail → pgn_notation → formatting
2. Modify formatting settings:
   You'll find several categories of formatting options:
   
   

   Element Colors and Styling:

   • "headers" - Color and bold styling for PGN header tags (Event, Site, Date, etc.)
   • "move_numbers" - Color and bold styling for move numbers (1., 2., etc.)
   • "moves" - Color and bold styling for chess moves (e4, Nf3, etc.)
   • "comments" - Color and italic styling for move comments
   • "variations" - Color and italic styling for move variations (alternative lines)
   • "results" - Color and bold styling for game results (1-0, 0-1, 1/2-1/2)

   Active Move Highlighting:

   • "active_move" - Background color, text color, and bold styling for the currently active move in the main line

   Annotation Display Settings:

   • "annotations.good" - Color and bold styling for good move annotations (!)
   • "annotations.bad" - Color and bold styling for poor move annotations (?)
   • "annotations.interesting" - Color and bold styling for interesting move annotations (!?)
   • "annotations.dubious" - Color and bold styling for dubious move annotations (?!)

   NAG (Numeric Annotation Glyph) Settings:

   • "nags.color" - Text color for NAG text
   • "nags.bold" - Whether NAG text is displayed in bold
   • "nags.italic" - Whether NAG text is displayed in italic

3. Example configuration:
   

   "formatting": {
       "headers": {
           "color": [100, 150, 255],
           "bold": true
       },
       "moves": {
           "color": [220, 220, 220],
           "bold": false
       },
       "annotations": {
           "use_symbols": true,
           "good": {
               "color": [100, 255, 100],
               "bold": true
           }
       },
       "nags": {
           "color": [200, 150, 255],
           "bold": false,
           "italic": true,
           "show_text": true
       },
       "comments": {
           "color": [180, 200, 255],
           "italic": true
       },
       "variations": {
           "color": [180, 180, 180],
           "italic": true
       },
       "results": {
           "color": [255, 255, 100],
           "bold": true
       },
       "active_move": {
           "background_color": [100, 120, 180],
           "text_color": [255, 255, 255],
           "bold": true
       }
   }

4. Save and restart:
   Save the file and restart CARA for the changes to take effect. The new formatting will apply to all PGN notation displayed in the Detail Panel.

7.1.7 Configuring Logging Settings

CARA provides configurable logging to help with debugging and troubleshooting. Logging can be configured for both console output and file output, with separate log levels for each.

Important: Console logging is only visible when you launch CARA from a terminal. This is always true for manual installations. For app bundles, it depends on the platform: Windows and macOS bundles are typically started via the GUI (no console), while Linux bundles can be started from a terminal to see console output.

To configure logging settings:

1. Locate the logging configuration:
   Open config.json in a text editor and navigate to: logging
2. Configure console logging:
   The console logging section contains:
   • "enabled": true - Enable or disable console logging. Set to false to disable console output.
   • "level": "ERROR" - Log level for console output. Valid values are: "DEBUG", "INFO", "WARNING", "ERROR". Only messages at or above this level will be displayed.
   Tip: If you’re using an app bundle and want console logs, start CARA from a terminal (especially on Linux). Otherwise, rely on file logs.
3. Configure file logging:
   The file logging section contains:
   • "enabled": true - Enable or disable file logging. Set to false to disable log file creation.
   • "level": "ERROR" - Log level for file output. Valid values are: "DEBUG", "INFO", "WARNING", "ERROR". Only messages at or above this level will be written to the log file.
   • "max_size_mb": 10 - Maximum size of the log file in megabytes before rotation. When the file reaches this size, it is rotated to a backup file.
   • "backup_count": 5 - Number of backup log files to keep. Older files are automatically deleted when this limit is exceeded.
   • "filename": "cara.log" - Base filename for log files. Log files are automatically timestamped with the date (e.g., cara_2026-01-15.log).
   Example configuration:

   "logging": {
       "console": {
           "enabled": true,
           "level": "ERROR"
       },
       "file": {
           "enabled": true,
           "level": "DEBUG",
           "max_size_mb": 10,
           "backup_count": 5,
           "filename": "cara.log"
       }
   }

4. Log file location:
   Log files are created in the same location as user_settings.json and engine_parameters.json:
   • Manual installations: Log files are created in the CARA root directory (where cara.py is located).
   • Windows app bundles: Log 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, log files are stored in %APPDATA%\CARA\ (usually C:\Users\YourUsername\AppData\Roaming\CARA\).
   • macOS app bundles: Log files are stored in ~/Library/Application Support/CARA/.
   • Linux app bundles: Log 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/.
   Finding Your Log Files: If you're using an app bundle and need to locate your log files:

   • Windows: First check the directory where CARA.exe is located. If the files are not there, press Win+R, type %APPDATA%\CARA, and press Enter to open the folder in File Explorer.
   • macOS: Open Finder, press ⌘+Shift+G (Go to Folder), type ~/Library/Application Support/CARA, and press Enter.
   • Linux: Use Help → Open User Data Directory to open the folder CARA is currently using.
5. Save and restart:
   Save the file and restart CARA for the changes to take effect.

7.1.7.1 Advanced Debug Logging

In addition to the standard logging levels, CARA provides detailed debug logging for UCI engine communication and AI service interactions. These debug logs provide detailed information about:

• UCI Lifecycle: Engine process lifecycle events (started, stopped, quit, crashed)
• UCI Outbound: Commands sent to chess engines (e.g., "uci", "isready", "position", "go")
• UCI Inbound: Responses received from chess engines (e.g., "uciok", "readyok", "bestmove")
• AI Outbound: Requests sent to AI services (OpenAI, Anthropic)
• AI Inbound: Responses received from AI services

To enable these advanced debug logs:

1. Enable the Debug menu:
   Open config.json in a text editor and navigate to: debug → show_debug_menu
   Set "show_debug_menu": true to enable the Debug menu in the application.
2. Restart CARA:
   After enabling the debug menu, restart CARA. The Debug menu will now appear in the menu bar.
3. Enable debug options:
   Use the Debug menu to enable the desired debug logging options:
   • Debug → Debug UCI Lifecycle - Enable UCI lifecycle event logging
   • Debug → Debug UCI Outbound - Enable UCI command logging
   • Debug → Debug UCI Inbound - Enable UCI response logging
   • Debug → Debug AI Outbound - Enable AI request logging
   • Debug → Debug AI Inbound - Enable AI response logging
   These options are checkable menu items that can be toggled on or off at runtime. When enabled, the corresponding debug messages will be written to the log file (if file logging is enabled) or displayed in the console.

7.2 Understanding user_settings.json

The user_settings.json file stores your personal preferences and settings. While most settings are managed through the application interface, understanding the file structure can be helpful for advanced users who want to manually edit settings or transfer configurations between installations.

7.2.1 File Structure

The file contains several main sections:

• moves_list_profiles: Column profile definitions with visibility, width, and order settings for each profile
• active_profile: The currently active column profile name
• board_visibility: Toggle states for board display elements (coordinates, arrows, evaluation bar, etc.)
• pgn_visibility: Toggle states for PGN notation display options
• game_analysis: Game analysis preferences (return to PLY 0, switch tabs, etc.)
• manual_analysis: Manual analysis settings (max pieces to explore, exploration depth, etc.)
• engines: List of configured engines with their paths and metadata
• engine_assignments: Engine assignments for each analysis task
• ai_models: AI model configurations for OpenAI and Anthropic providers
• ai_summary: AI Summary preferences
• annotations: Annotation color palette and font settings

7.2.2 Manual Editing Considerations

While you can manually edit user_settings.json, be aware that:

• The file is automatically overwritten when you save settings through the application
• Invalid JSON syntax will cause the application to fail loading settings (it will fall back to defaults)
• Some settings have dependencies (e.g., active_profile must reference a profile that exists in moves_list_profiles)
• It's recommended to close CARA before editing the file to avoid conflicts

7.3 Understanding engine_parameters.json

The engine_parameters.json file stores engine-specific parameters and options for each configured chess engine. This file is automatically managed by the application, but understanding its structure can help with advanced engine configuration.

7.3.1 File Structure

The file contains a dictionary mapping engine IDs to parameter configurations. Each engine entry includes:

• Per-task parameters: Separate parameter sets for evaluation, game_analysis, and manual_analysis tasks
• Thread count: Number of CPU threads to use
• Depth limits: Maximum search depth
• Time limits: Time per move or position
• Engine-specific options: UCI options specific to each engine (e.g., Hash size, MultiPV, etc.)

7.3.2 Manual Editing

Manual editing of engine_parameters.json is generally not recommended, as the application manages this file automatically. However, if you need to make advanced changes:

• Close CARA before editing to avoid conflicts
• Ensure the engine ID matches an engine in user_settings.json
• Validate that UCI option names and values are correct for your engine
• Back up the file before making changes

7.4 PGN Metadata Tags Used by CARA

CARA uses several custom PGN metadata tags to store analysis data and annotations. Understanding these tags can help you work with CARA-generated PGN files in other applications or manually inspect the stored data.

7.4.1 Analysis Data Tags

When "Store Analysis results in PGN Tag" is enabled, CARA stores analysis data in compressed format:

• [CARAAnalysisData "..."]: Contains compressed, base64-encoded JSON data with evaluations, CPL values, move classifications, best moves, and engine depths for each move
• [CARAAnalysisInfo "..."]: Contains metadata about the analysis (app version, creation date/time)
• [CARAAnalysisChecksum "..."]: SHA-256 checksum for data integrity validation

The analysis data is stored as gzip-compressed JSON, then base64-encoded to ensure it's valid within PGN tag values. This keeps the PGN file size manageable while preserving all analysis information.

7.4.2 Annotation Tags

When annotations are saved to a game, CARA stores them in a similar compressed format:

• [CARAAnnotations "..."]: Contains compressed, base64-encoded JSON data with all annotation objects (text, arrows, circles, squares) organized by move (ply index)
• [CARAAnnotationsInfo "..."]: Contains metadata about the annotations (app version, creation date/time)
• [CARAAnnotationsChecksum "..."]: SHA-256 checksum for data integrity validation

Each annotation includes its type, position, color, size, rotation, and other properties. The data is compressed and encoded to keep PGN files clean and manageable.

7.4.3 Tag Visibility

These custom tags are automatically hidden from the PGN Notation Pane display to keep the move notation clean. They are always excluded from PGN view, regardless of the "Show Non-Standard Tags" setting. The tags remain in the PGN file and are preserved when saving databases.

7.5 Troubleshooting

This section covers common issues and their solutions.

7.5.1 Application Won't Start

If CARA fails to start, check the following:

• Invalid config.json: If you've edited config.json, verify the JSON syntax is valid. Use a JSON validator or text editor with JSON syntax checking. Restore from backup if needed.
• Missing dependencies: Ensure all required Python libraries are installed. Run pip list to verify PyQt6, python-chess, requests, asteval, and charset-normalizer are present.
• Python version: Verify you're using Python 3.8 or higher with python --version.

7.5.2 Engine Validation Errors

If an engine fails validation:

• Check engine path: Ensure the engine executable path is correct and the file exists
• Verify UCI support: The engine must support the UCI (Universal Chess Interface) protocol
• Check permissions: Ensure the engine executable has execute permissions
• Test engine manually: Try running the engine from the command line to verify it works

7.5.3 Settings Not Persisting

If your settings aren't being saved:

• Check file permissions: Ensure CARA has write permissions in its directory for user_settings.json and engine_parameters.json
• Verify file location: Check that settings files are being created in the CARA root directory
• Check for errors: Look for error messages in the status bar or console output

7.5.4 Analysis Not Working

If game analysis isn't working:

• Verify engine assignment: Ensure an engine is assigned to the "Game Analysis" task via Engines → [Engine Name] → Set as Game Analysis Engine
• Check engine status: Verify the engine is valid and can be started
• Review engine parameters: Check that engine parameters (threads, depth, time) are reasonable
• Check system resources: Ensure you have sufficient CPU and memory available

7.6 Performance Optimization

This section provides tips for optimizing CARA's performance, especially when working with large databases or performing intensive analysis.

7.6.1 Engine Configuration

Optimize engine performance by configuring appropriate parameters:

• Thread count: Set thread count to match your CPU core count for maximum parallelization. For bulk analysis, CARA automatically optimizes thread usage across multiple games.
• Task-specific engines: Use a fast engine for evaluation (continuous updates) and a stronger engine for deep game analysis
• Depth vs. time: For faster analysis, use time limits rather than depth limits. For deeper analysis, use depth limits with appropriate thread counts

7.6.2 Database Management

Improve performance when working with large databases:

• Split large databases: Consider splitting very large databases (10,000+ games) into smaller files for faster loading and searching
• Use search filters: Use the search function to work with filtered subsets rather than loading entire large databases
• Close unused databases: Close database tabs you're not actively using to free memory

7.6.3 Analysis Workflow

Optimize your analysis workflow:

• Bulk analysis: Use bulk analysis for multiple games rather than analyzing them individually. CARA automatically parallelizes analysis across available CPU cores
• Disable unnecessary features: Turn off features you're not using (e.g., positional heatmap, evaluation bar) during analysis to reduce overhead
• Store analysis results: Enable "Store Analysis results in PGN Tag" to avoid re-analyzing games, but be aware this increases PGN file size

7.7 Moves List Columns Reference

The following table describes all available columns:

7.8 Customizing ELO and Accuracy Formulas

CARA allows you to customize the formulas used to calculate estimated ELO ratings and accuracy percentages for players. These formulas are defined in config.json.

7.8.1 Configuration Location

The formula configurations are located in config.json under the game_analysis section:

• game_analysis → elo_estimation - Formula for estimating player ELO
• game_analysis → accuracy_formula - Formula for calculating overall player accuracy
• game_analysis → phase_accuracy_formulas - Formulas for calculating phase-specific accuracy (opening, middlegame, endgame)

7.8.2 Formula Structure

Each formula configuration contains the following fields:

• formula: A string containing the mathematical expression to evaluate. If omitted or empty, CARA uses the default formula.
• value_on_error: The value to return if the formula evaluation fails (default: 0 for ELO, 0.0 for accuracy).
• _examples: (Optional) A dictionary of example formulas for reference. These are not used by the application but serve as documentation.

7.8.3 Available Variables

Variables for Overall Accuracy and ELO Formulas: The following variables are available for use in overall accuracy and ELO estimation formulas:

• total_moves: Total number of moves in the game (integer)
• non_book_moves: Number of moves analyzed (excluding book moves) (integer)
• book_moves: Number of book moves (moves found in opening books) (integer)
• blunders: Number of blunders made by the player (integer)
• mistakes: Number of mistakes made by the player (integer)
• inaccuracies: Number of inaccuracies made by the player (integer)
• misses: Number of missed opportunities (e.g., missing a checkmate, missing a winning move, or missing a critical tactical opportunity) (integer)
• best_moves: Number of best moves played (integer)
• good_moves: Number of good moves played (integer)
• brilliant_moves: Number of brilliant moves played (integer)
• average_cpl: Average centipawn loss across all analyzed moves (float)
• median_cpl: Median centipawn loss across all analyzed moves (float)
• min_cpl: Minimum centipawn loss (best move) (float)
• max_cpl: Maximum centipawn loss (worst move) (float)
• blunder_rate: Blunder rate as a decimal (0.0 to 1.0) (float)
• mistake_rate: Mistake rate as a decimal (0.0 to 1.0) (float)
• accuracy: Calculated accuracy percentage (0.0 to 100.0) (float) - Note: This variable is only available in the ELO formula, not in the accuracy formula itself (to avoid circular dependency)
• has_won: 1 if the player won the game, 0 otherwise (integer)
• has_drawn: 1 if the game was a draw or had an undefined result, 0 otherwise (integer)
• opening_moves: Total number of moves in the opening phase (integer)
• middlegame_moves: Total number of moves in the middlegame phase (integer)
• endgame_moves: Total number of moves in the endgame phase (integer)
• average_cpl_opening: Average centipawn loss in the opening phase (float)
• average_cpl_middlegame: Average centipawn loss in the middlegame phase (float)
• average_cpl_endgame: Average centipawn loss in the endgame phase (float)

Variables for Phase-Specific Accuracy Formulas: Phase-specific accuracy formulas (opening, middlegame, endgame) have access to all the variables above, plus the following phase-specific and overall comparison variables:

• total_moves: Number of moves in this specific phase (integer) - Note: In phase formulas, this refers to the phase-specific move count, not the overall game
• blunders: Number of blunders in this specific phase (integer)
• mistakes: Number of mistakes in this specific phase (integer)
• inaccuracies: Number of inaccuracies in this specific phase (integer)
• misses: Number of misses in this specific phase (integer)
• best_moves: Number of best moves in this specific phase (integer)
• good_moves: Number of good moves in this specific phase (integer)
• brilliant_moves: Number of brilliant moves in this specific phase (integer)
• blunder_rate: Blunder rate for this specific phase (0.0 to 1.0) (float)
• mistake_rate: Mistake rate for this specific phase (0.0 to 1.0) (float)
• average_cpl: Average centipawn loss for this specific phase (float) - Note: In phase formulas, this refers to the phase-specific CPL
• total_moves_overall: Total number of moves in the entire game (integer)
• non_book_moves_overall: Total number of analyzed moves in the entire game (integer)
• book_moves_overall: Total number of book moves in the entire game (integer)
• blunders_overall: Total number of blunders in the entire game (integer)
• mistakes_overall: Total number of mistakes in the entire game (integer)
• inaccuracies_overall: Total number of inaccuracies in the entire game (integer)
• misses_overall: Total number of misses in the entire game (integer)
• best_moves_overall: Total number of best moves in the entire game (integer)
• good_moves_overall: Total number of good moves in the entire game (integer)
• brilliant_moves_overall: Total number of brilliant moves in the entire game (integer)
• blunder_rate_overall: Overall blunder rate for the entire game (0.0 to 1.0) (float)
• mistake_rate_overall: Overall mistake rate for the entire game (0.0 to 1.0) (float)
• average_cpl (overall context): Overall average centipawn loss for the entire game (float) - Note: This is also available as a separate variable for comparison

7.8.4 Available Functions

The following functions are available in all formulas:

• min(x, y): Returns the minimum of two values
• max(x, y): Returns the maximum of two values
• abs(x): Returns the absolute value of a number
• int(x): Converts a value to an integer
• not(x): Returns the logical negation of a value (1 if x is 0/false, 0 if x is non-zero/true)

Standard mathematical operators are also supported: +, -, *, /, ** (exponentiation), and parentheses for grouping.

7.8.5 ELO Estimation Formula

The ELO estimation formula calculates an estimated ELO rating based on player performance. You should use max(0, ...) in your formula to ensure negative ELO values are not returned.

Default Formula:

"formula": "max(0, int(2800 - (average_cpl * 8.5) - ((blunder_rate * 50 + mistake_rate * 20) * 40)))"

Example Custom Formulas:

A simplified formula that only considers average centipawn loss:

"formula": "max(0, int(2800 - (average_cpl * 10)))"

Add a bonus for wins and a penalty for losses (when the player has not won and has not drawn):

"formula": "max(0, int(2800 - (average_cpl * 8.5) - ((blunder_rate * 50 + mistake_rate * 20) * 40) + (has_won * 50) - ((1 - has_won) * (1 - has_drawn) * 30)))"

Directly converts accuracy percentage to ELO (e.g., 90% accuracy ≈ 2520 ELO):

"formula": "max(0, int(accuracy * 28))"

7.8.6 Accuracy Formula

The accuracy formula calculates a player's accuracy percentage. You should use max(min_value, min(100.0, your_formula)) in your formula to ensure the result stays within the desired range (typically 0.0 to 100.0, though the default formula uses 5.0 as the minimum).

Default Formula:

"formula": "max(5.0, min(100.0, 100.0 - (average_cpl / 3.5)))"

Example Custom Formulas:

A simplified formula with a different scaling factor:

"formula": "100.0 - (average_cpl / 2.0)"

Ensures accuracy never drops below 10%:

"formula": "max(10.0, 100.0 - (average_cpl / 3.0))"

Applies an additional penalty based on blunder rate:

"formula": "max(0.0, 100.0 - (average_cpl / 3.5) - (blunder_rate * 100))"

7.8.7 Phase-Specific Accuracy Formulas

CARA supports separate accuracy formulas for each game phase (opening, middlegame, and endgame). These formulas are configured under game_analysis → phase_accuracy_formulas in config.json.

Each phase has its own formula configuration with the same structure as the overall accuracy formula:

• phase_accuracy_formulas → opening → formula - Formula for opening phase accuracy
• phase_accuracy_formulas → middlegame → formula - Formula for middlegame phase accuracy
• phase_accuracy_formulas → endgame → formula - Formula for endgame phase accuracy

Default Phase Formulas:

"opening": {
    "formula": "max(5.0, min(100.0, 100.0 - (average_cpl_opening / 3.5)))",
    "value_on_error": 0.0
},
"middlegame": {
    "formula": "max(5.0, min(100.0, 100.0 - (average_cpl_middlegame / 3.5)))",
    "value_on_error": 0.0
},
"endgame": {
    "formula": "max(5.0, min(100.0, 100.0 - (average_cpl_endgame / 3.5)))",
    "value_on_error": 0.0
}

Example: Comparing Phase Performance to Overall Game:

"formula": "max(5.0, min(100.0, 100.0 - (average_cpl_opening / 3.5) - ((blunder_rate - blunder_rate_overall) * 30.0)))"

This formula penalizes the opening phase accuracy if the opening blunder rate is higher than the overall game blunder rate.

7.8.8 Editing Formulas

To customize a formula:

Locate the formula configuration:
Open config.json in a text editor and navigate to: game_analysis → elo_estimation, game_analysis → accuracy_formula, or game_analysis → phase_accuracy_formulas (for phase-specific formulas)

Modify the formula string:
Edit the "formula" field with your desired expression. For example:

"elo_estimation": {
    "formula": "max(0, int(2800 - (average_cpl * 10)))",
    "value_on_error": 0
}

Set error handling (optional):
Adjust "value_on_error" to specify what value should be returned if the formula evaluation fails. This is useful for debugging or providing fallback values.

Save and restart:
Save the file and restart CARA for the changes to take effect. The new formulas will be used for all game summaries and player statistics calculations.

7.8.9 Player Statistics

When calculating player statistics across multiple games, CARA calculates ELO and accuracy for each individual game using the configured formulas, then averages these values. This approach ensures that each game contributes equally to the final statistics, regardless of game length or number of moves analyzed.

For example, if a player has three games with ELO estimates of 1800, 1900, and 2000, the player's average ELO will be 1900, not a single calculation based on all moves combined.

7.9 Using a Custom AI Endpoint (Local LLM)

CARA can use any OpenAI-compatible API as an AI Summary provider. That includes local servers such as LM Studio or Ollama, so you can run a model on your own machine for privacy, no cloud cost, or offline use.

7.9.1 Setup with LM Studio

1. Install and run LM Studio: Download and install LM Studio, then load a model of your choice.
2. Start the local server: In LM Studio, start the Local Server and note the Server URL (e.g. http://localhost:1234/v1).
3. Configure CARA: Open AI Summary → AI Model Settings.... Enable Enable custom endpoint, set Base URL to the server URL (or accept the default if it matches), and leave API Key empty for LM Studio. Click Refresh Models, then select a Default Model. Adjust Request timeout (seconds) if needed.
4. Use the custom provider: Choose AI Summary → Use Custom Endpoint so CARA uses your local model for AI Summary.

7.9.2 Other OpenAI-Compatible Servers

The same custom endpoint flow works with other servers that expose an OpenAI-compatible API (e.g. Ollama, or your own deployment). Use their base URL in AI Model Settings and, if required, add an API key.

7.9.3 Troubleshooting

• Server not responding: Ensure the local server is running and a model is loaded before sending requests.
• Wrong or unreachable URL: Verify the Base URL matches the server (e.g. http://localhost:1234/v1 for LM Studio’s default).
• Requests fail or time out: Increase the request timeout in AI Model Settings and confirm a model is loaded.
• API error 400 – context length: The prompt exceeds the model’s context window. Configure and reload the model with a larger context length in your server (e.g. LM Studio), or reduce the amount of data sent in the prompt by disabling AI Summary → Include Game Analysis Data in Pre-Prompt and AI Summary → Include PGN header tags in pre-prompt.
• Output used only for reasoning: The model might use the full output context only for reasoning, leaving no room for the actual answer. Disable reasoning/thinking in your server. In LM Studio you can do this by adding {%- set enable_thinking = false %} to the prompt template (Jinja) in AI Model Settings.

7.10 Recommended Chess Engines

CARA works with any UCI-compatible engine. If you just want one strong default, start with Stockfish.

Recommended free engines

Conventional (alpha-beta) engines are typically faster, making them a great choice for responsive analysis and day-to-day use. They run well on standard CPUs and don’t require specialized hardware.

• Stockfish — Best all-around choice for most users (fast, strong, easy to set up).
• RubiChess — Strong conventional engine; a good second opinion next to Stockfish.
• Berserk — Strong and fast; useful as an alternative to Stockfish for comparison.
• PlentyChess — Strong modern engine; good for comparing evaluations and getting another top-tier viewpoint.

Neural network-based engines can provide a different evaluation perspective. They are often slower and may benefit from stronger hardware (especially a GPU, depending on the engine/build), but they can be very insightful for exploring plans and positional ideas.

• Leela Chess Zero (Lc0) — Neural-network engine; great for alternative perspectives (often benefits from a GPU).
• Maia — Human-like play style (Lc0-based); useful when you want “human” plans rather than pure engine perfection.

Recommended commercial engines

• Shredder — Mature engine with a long track record; good as a paid “second opinion”.
• Komodo — Strong commercial engine; useful if you already own it and want to compare styles.
• HIARCS — Commercial engine with a distinct style; useful as a paid “second opinion” and for comparison.

Best use cases inside CARA

• Evaluation bar (continuous): Use a fast conventional engine (Stockfish is a great default).
• Game Analysis: Use a fast conventional engine. If you use a neural network-based engine, set a longer movetime to get stable results.
• Manual Analysis: Use either a conventional or a neural network-based engine—this is a great place to compare “styles” and explore plans.
• Brilliancy Detection: Experiment with using a different, slightly weaker conventional engine as a second opinion. Avoid neural network-based engines here. See section 5.5.3 “Brilliant Move Detection”.