Documentation

Learn how to install, configure, and play chess in your terminal.

A minimal, elegant command-line tool that lets you solve Lichess puzzles and play full games against a local AI directly in your terminal.

Built for developers and terminal power users who want a quick chess puzzle fix without leaving their command line. No account required, no configuration needed.

Features

  • Zero auth: No Lichess account required.
  • Graphical Board: Optional high-fidelity Unicode rendering with colored squares for modern terminals.
  • Local-first: All user data (stats, history) lives on your machine.
  • Local AI: Play full games vs Stockfish (downloads on first use).
  • Game Resume: Automatically save your AI games and resume them later.
  • Single binary: Fast, self-contained executable.

Installation

macOS and Linux

Install chesshell using our quick installer script:

curl -fsSL https://chesshell.pages.dev/install.sh | bash

Windows

Open PowerShell as an Administrator and run the following command to automatically download and install chesshell and add it to your PATH:

iwr -useb https://chesshell.pages.dev/install.ps1 | iex

Usage

Play the Daily Puzzle

Fetch today's featured puzzle from Lichess and start an interactive session:

chesshell play

Play against Local AI

Play a full chess game directly in your terminal against Stockfish. You can select your difficulty and your preferred color (White or Black).

chesshell play --ai

Resume a Game

If you close your terminal during an AI game, you can pick up exactly where you left off:

chesshell resume

Graphical Board (Unicode)

chesshell automatically detects if your terminal supports graphical pieces. You can manually override this or save your preference:

  • Force once: chesshell play --unicode
  • Save preference: chesshell config unicode on (or off)

View Stats and History

Check your aggregate stats or a table of your most recent attempts:

chesshell stats
chesshell history

How It Works

chesshell interacts with the public, unauthenticated endpoints of the Lichess API to fetch puzzle data.

For AI games, it runs Stockfish locally via the UCI protocol. If Stockfish is not found on your system PATH, chesshell caches a downloaded copy under your OS config directory.

Input Format

When playing, enter moves using UCI (Universal Chess Interface) notation.

  • Example: e2e4 (moves a piece from e2 to e4)
  • Captures: f3d5 (moves piece to capture on d5)
  • Promotion: e7e8q (promotes to queen)

Type hint (or h) in puzzles to see the starting square of the correct move. Type quit (or q) to abandon a session.

Uninstalling

To completely remove chesshell, its local data, and cached engine:

chesshell uninstall

License

This project is licensed under the MIT License - see the LICENSE file for details.

A minimal, high-performance chess tool for the terminal. chesshell is designed to provide a distraction-free environment for chess puzzles and AI games, prioritizing speed, local-first data persistence, and zero-configuration setup.

Architecture Overview

The project is structured into several modular packages within the internal/ directory, following standard Go project layouts.

internal/board

The core state machine. It wraps the github.com/corentings/chess library to manage game logic.

  • Rendering: Implements two distinct rendering pipelines:
    • Graphical (Unicode): Uses Unicode chess glyphs, ANSI background colors for square parity, and high-contrast foreground coloring.
    • Classic (ASCII): A fallback renderer for legacy terminals using alphanumeric characters.
  • Detection: Automatically detects terminal capabilities (UTF-8 support) via environment variable analysis (LANG, TERM, etc.).

internal/engine

Manages communication with the Stockfish chess engine.

  • UCI Protocol: Implements the Universal Chess Interface (UCI) protocol via stdin/stdout pipes.
  • Lifecycle: Handles the automatic downloading, caching, and execution of platform-specific Stockfish binaries if they are not found in the system PATH.

internal/api

A thin client for the Lichess.org API.

  • Zero Auth: Uses public, unauthenticated endpoints to fetch daily puzzles or specific puzzle IDs.
  • Fault Tolerance: Implements custom error handling for rate-limiting (429) and network timeouts.

internal/store

The persistence layer.

  • Local-First: Data is stored in a single data.json file in the user's config directory (e.g., ~/.config/chesshell/).
  • State Management: Tracks aggregate statistics, puzzle history, and the Resume state for unfinished AI games.

Project Structure

├── cmd/                # Cobra command definitions (entry points)
├── internal/
│   ├── api/            # Lichess API integration
│   ├── board/          # Board logic and ASCII/Unicode rendering
│   ├── engine/         # Stockfish process management & binary downloader
│   ├── puzzle/         # Session managers for Puzzles and AI Games
│   └── store/          # JSON persistence and data models
├── main.go             # Application entry point
└── data.json           # (Created at runtime) Local state & config

Development & Contribution

Prerequisites

  • Go: 1.26.2 or higher.
  • Git: For version control.
  • Stockfish: (Optional) The tool will download it automatically, but you can use a system-installed version if available in your PATH.

Building from Source

git clone https://github.com/Killiivalavan/chesshell-cli.git
cd chesshell-cli
go build -o chesshell main.go

Core Principles for Contributors

When contributing, please adhere to these architectural constraints:

  • Minimalism: Avoid adding dependencies. Prefer the Go standard library or high-quality, lightweight packages.
  • Zero Config: Features should work immediately. If a feature requires configuration, provide sensible defaults and an interactive setup.
  • Local-First: Never require a network connection for features that don't strictly need it (like AI games or stats).
  • Non-Destructive Migrations: When updating data.json schemas, ensure old versions are migrated without data loss.

Code Style

  • Run go fmt ./... before committing.
  • Ensure all exported symbols have concise, descriptive comments.
  • Keep the cmd/ package thin; move business logic into internal/.

Data Schema (data.json)

The application persists data using the following schema:

  • config: User preferences (e.g., unicode mode).
  • stats: Aggregate win/loss and solve counts.
  • aiGames: Specific records for games against Stockfish.
  • currentGame: Mid-game state (FEN and difficulty) to support the Resume feature.
  • history: A rolling buffer of the last 200 puzzle attempts.

License

This project is licensed under the MIT License. See LICENSE for details.