Analyze your Lichess games to identify recurring weakness patterns and get coaching insights.
- Python 3.13+
- Stockfish chess engine (install via
brew install stockfishon macOS) - uv package manager (recommended) or pip
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the project in development mode
uv pip install -e .# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the project in development mode
pip install -e .# Run initialization (creates config, database, downloads opening book)
caissa init
# View configuration
caissa config show
# Set your Lichess username
caissa config set lichess.username YOUR_USERNAME# Fetch your last 100 games
caissa fetch games YOUR_USERNAME
# Fetch with options
caissa fetch games YOUR_USERNAME --max 50 --time-control rapid --since 2024-01-01
# Fetch a single game by ID
caissa fetch game GAME_ID# Analyze all fetched games with Stockfish (detects patterns automatically)
caissa analyze
# Analyze a specific game
caissa analyze game GAME_ID --depth 18
# Re-analyze already analyzed games
caissa analyze --force
# Re-run pattern detection on already analyzed games (no Stockfish needed)
caissa analyze patterns# Show weakness pattern summary across all games
caissa report summary
# Show detailed report for a single game
caissa report game GAME_ID
# Export as JSON for further analysis
caissa report game GAME_ID --format json
caissa report summary --format jsonCaissa detects the following weakness patterns:
| Pattern | Description |
|---|---|
| Missed Tactic | Generic tactical miss with high centipawn loss |
| Missed Mate | Had a winning checkmate but missed it |
| Missed Fork | Best move was a fork attacking 2+ pieces |
| Missed Pin | Best move created an absolute pin |
| Missed Skewer | Best move was a skewer |
| Hanging Piece | Left a piece undefended |
| Time Trouble Blunder | Blunder with < 30s on clock |
| Premature Move | Moved too quickly (< 3s) and made an error |
| Opening/Middlegame/Endgame Error | Phase-specific errors (fallback category) |
# Setup
caissa init # Initialize: download book, init DB, configure
caissa config show # Show configuration
caissa config set <key> <value> # Set config value
# Fetch games
caissa fetch games [USERNAME] # Fetch games from Lichess
--since DATE # Games after date (YYYY-MM-DD)
--max N # Max games to fetch (default: 100)
--time-control TC # bullet|blitz|rapid|classical|all
--rated/--all-games # Rated only (default) or all
caissa fetch game <GAME_ID> # Fetch single game by ID
# Analysis
caissa analyze # Analyze fetched games with Stockfish
--depth N # Stockfish depth (default: 18)
--force # Re-analyze already analyzed games
--max N # Max games to analyze
--username USER # Analyze specific user's games
caissa analyze game <GAME_ID> # Analyze a single game
caissa analyze patterns # Re-run pattern detection only
--username USER # For specific user
--force # Clear and re-detect
# Reports
caissa report summary # Pattern summary across all games
--top N # Show top N patterns (default: 10)
--format rich|json # Output format
--username USER # For specific user
caissa report game <GAME_ID> # Detailed single game report
--format rich|json # Output format
--all # Show all moves, not just mistakes Top 10 Patterns
┏━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ # ┃ Pattern ┃ Count ┃ Avg CP Loss ┃ Total CP Loss ┃ Impact ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ 1 │ Missed Tactic │ 292 │ 2598 │ 758581 │ 758581 │
│ 2 │ Missed Mate │ 16 │ 8626 │ 138020 │ 138020 │
│ 3 │ Hanging Piece │ 141 │ 952 │ 134170 │ 134170 │
│ ... │
└────┴──────────────────┴───────┴─────────────┴───────────────┴────────┘
╭───────────────────────────────── Game Info ──────────────────────────────────╮
│ ID: 9TqS7N66 │
│ URL: https://lichess.org/9TqS7N66 │
│ Player: username (white) │
│ Result: loss (0-1) │
╰──────────────────────────────────────────────────────────────────────────────╯
17. Ne3 ?!
Best move: Nxf6+
Eval drop: 86 cp
Phase: middlegame
Pattern: Missed Fork
Tactic: fork
Targets: bishop, king
# Install with dev dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy src/caissa
# Linting
ruff check src/caissacaissa/
├── src/caissa/
│ ├── cli/ # Command-line interface (Typer)
│ ├── core/ # Config and data models
│ ├── ingestion/ # Lichess API client
│ ├── extraction/ # PGN parsing, phase detection
│ ├── analysis/ # Stockfish evaluation, opening book
│ ├── patterns/ # Pattern detection (tactical, time trouble)
│ ├── synthesis/ # LLM prompt generation (coming soon)
│ └── persistence/ # SQLite database
├── docs/ # Documentation
├── tests/
├── PLAN.md # Implementation roadmap
└── README.md
User data is stored in ~/.local/share/caissa/:
caissa.db- SQLite database with games, positions, mistakes, patternsbooks/gm2600.bin- Opening book (auto-downloaded)
Configuration is stored at ~/.config/caissa/config.toml:
[lichess]
username = "your_username"
default_time_controls = ["blitz", "rapid"]
[stockfish]
path = "" # Auto-detected if empty
depth = 18
[analysis]
inaccuracy_threshold = 50 # centipawns
mistake_threshold = 100
blunder_threshold = 200
time_trouble_seconds = 30- Phase 1: Foundation (config, database, CLI skeleton)
- Phase 2: Ingestion (Lichess API client, fetch command)
- Phase 3: Extraction (PGN parsing, phase detection)
- Phase 4: Analysis (Stockfish evaluation)
- Phase 5: Pattern Detection (tactical, time trouble, phase-based)
- Phase 6: Reporting (summary, game reports) - partial, LLM prompts pending
- Phase 7: TUI (Post-MVP)
See PLAN.md for detailed implementation phases.