Bot Configuration

Chess-tui allows you to configure the behavior of the computer opponent (bot) when playing against a chess engine.

Chess Engine Setup

Before you can play against a bot, you need to configure a UCI-compatible chess engine.

Quick Setup (Recommended) ⭐

The easiest way to set up a chess engine is using the automatic installation script for Stockfish:

./scripts/install-stockfish.sh

This script will:

• Detect your operating system (macOS, Linux)
• Install Stockfish using the appropriate package manager
• Automatically configure the engine path in your chess-tui config file
• Work on macOS (Homebrew), Debian/Ubuntu (apt), Fedora (dnf), and Arch Linux (pacman)

After running the script, you can immediately start playing against the bot - no manual configuration needed!

Manual Engine Configuration

If you prefer to install the engine manually or use a different engine, you can configure it yourself.

Configuration File

Set the path to your chess engine in the configuration file:

engine_path = "/path/to/your/engine"

Command Line Configuration

You can also set the engine path via command line:

# Simple path
chess-tui -e /path/to/your/engine

# Path with command-line arguments (e.g., GNU Chess)
chess-tui -e "/opt/homebrew/bin/gnuchess --uci"

Or with the long form:

chess-tui --engine-path /path/to/your/engine
chess-tui --engine-path "/opt/homebrew/bin/gnuchess --uci"

The path will be automatically saved to your configuration file for future use.

Supported Engines

Any UCI-compatible chess engine should work. Some popular options include:

• Stockfish - Popular open-source engine (recommended). Supports the difficulty presets via UCI ELO limiting.
• GNU Chess - Classic chess engine (requires --uci flag)
• Leela Chess Zero - Neural network engine
• Komodo - Commercial engine

note

The engine path must point to a valid UCI-compatible chess engine executable. If not configured correctly, the bot play option will be disabled.

Engines Requiring Command-Line Arguments

Some chess engines require command-line arguments to enable UCI mode. For example, GNU Chess requires the --uci flag. You can specify these arguments directly in the engine path:

Command Line:

chess-tui -e "/opt/homebrew/bin/gnuchess --uci"

Configuration File:

engine_path = "/opt/homebrew/bin/gnuchess --uci"

tip

When using quotes in the command line, use double quotes to ensure the entire path and arguments are treated as a single value. In the configuration file, quotes are not needed.

Common Engine Paths

Stockfish:

• macOS (Homebrew): /opt/homebrew/bin/stockfish or /usr/local/bin/stockfish
• Linux (apt): /usr/bin/stockfish
• Linux (dnf/pacman): /usr/bin/stockfish

GNU Chess (requires --uci flag):

• macOS (Homebrew): /opt/homebrew/bin/gnuchess --uci or /usr/local/bin/gnuchess --uci
• Linux (apt): /usr/bin/gnuchess --uci
• Linux (dnf/pacman): /usr/bin/gnuchess --uci

Bot Configuration

Bot settings can be configured in the CONFIG_DIR/chess-tui/config.toml file:

# Bot thinking depth for chess engine (1-255, default: 10)
# Used when difficulty is "Off" (full strength)
bot_depth = 10

# Bot difficulty preset (optional): 0=Easy, 1=Medium, 2=Hard, 3=Magnus
# Omit or set to null for full strength
bot_difficulty = 0

CONFIG_DIR is typically:

• Linux: $XDG_CONFIG_HOME or $HOME/.config
• macOS: $HOME/Library/Application Support
• Windows: %APPDATA% (Roaming AppData folder)

Command Line Override

You can also set the bot depth directly from the command line, which will override the configuration file value for that session:

chess-tui --depth 15
# or
chess-tui -d 15

This is useful for:

• Testing different depth values without editing the config file
• Setting a custom depth for a specific game session
• Overriding the default depth temporarily

Difficulty Preset

You can also set the bot difficulty from the command line:

chess-tui --difficulty easy
chess-tui --difficulty medium
chess-tui --difficulty hard
chess-tui --difficulty magnus

Difficulty Selection

When configuring a game against the bot, you can select a difficulty preset instead of playing at full engine strength. Use the ← and → arrow keys in the game setup form to cycle through the options:

Preset	Approx. ELO	Best for
Off	Full strength	Experienced players
Easy	400	Beginners, learning
Medium	900	Casual play
Hard	1500	Intermediate
Magnus	2700	Strong players

Works great with Stockfish

Stockfish supports the UCI UCI_LimitStrength and UCI_Elo options natively. When you select a difficulty preset, chess-tui uses these options so Stockfish plays at the corresponding strength level. This gives you smooth, predictable scaling from beginner to near-grandmaster level.

For engines that don't support ELO limiting (e.g. GNU Chess), chess-tui still weakens the bot by limiting search depth and thinking time per move. Lower difficulties use shallower depth and less time, so the bot will make quicker but weaker moves.

Bot Depth

The bot_depth parameter controls how deeply the chess engine analyzes positions:

• Lower values (1-5): Faster moves, weaker play
• Medium values (6-15): Balanced speed and strength (recommended for most users)
• Higher values (16+): Stronger play, but slower moves

Default Value

The default bot depth is 10, which provides a good balance between playing strength and response time.

Performance Impact

• Depth 1-5: Moves are calculated almost instantly
• Depth 6-10: Moves typically take 1-5 seconds
• Depth 11-15: Moves may take 5-30 seconds
• Depth 16+: Moves can take several minutes or more

tip

For casual play, a depth of 8-12 is usually sufficient. For serious analysis or when you have time to wait, you can increase the depth to 15-20.

warning

Very high depth values (20+) can cause the engine to think for a very long time, especially in complex positions. Use these values only when you have plenty of time and want maximum playing strength.

Verifying Your Setup

To verify your engine is configured correctly:

1. Launch chess-tui
2. Navigate to the "Play Bot" menu option
3. If your engine path is valid, you'll be able to select your color and start playing
4. If there's an issue, you'll see an error message with instructions

Troubleshooting

Engine Path Not Found

If you see an error that the engine path is invalid:

1. Check the path: Make sure the path points to an actual executable file
2. Verify permissions: Ensure the file is executable (chmod +x /path/to/engine)
3. Test manually: Try running the engine from the command line to verify it works
4. Use the install script: If using Stockfish, try the automatic installation script

Engine Not Responding

If the engine path is valid but the engine doesn't respond during gameplay:

1. Check UCI compatibility: Ensure your engine supports the UCI protocol
2. Add required flags: Some engines (like GNU Chess) require command-line arguments to enable UCI mode:

   chess-tui -e "/opt/homebrew/bin/gnuchess --uci"
3. Test UCI mode: Test the engine manually in UCI mode:

   echo "uci" | /path/to/engine --uci
   You should see uciok in the response
4. Check logs: Enable logging to see detailed error messages:

   chess-tui -e /path/to/engine
   # Then check logs in CONFIG_DIR/chess-tui/logs/