GameAdvisor

Real-time PC screen analysis and move suggestion assistant. Press a hotkey while any game is open — GameAdvisor captures your screen, identifies the game, and displays move recommendations in a transparent overlay.

Supports Chess (Stockfish engine), Poker (equity calculator), and any other game (direct Claude Vision strategic advice).

---

Requirements

• Windows 10/11 (64-bit)
• Python 3.11 or newer
• An Anthropic API key
• (Optional but recommended) Stockfish binary for chess analysis

---

Installation

1. Clone or download this repository

git clone <repo-url>
cd gameadvisor

2. Install Python dependencies

pip install -r requirements.txt

If you do not want chess support, you can skip stockfish and chess: pip install mss anthropic PyQt6 Pillow treys keyboard

3. Set your Anthropic API key

Option A — environment variable (recommended)

# Windows Command Prompt
set ANTHROPIC_API_KEY=sk-ant-...

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Option B — config.json Open config.json (created on first run) and set:

{
  "anthropic_api_key": "sk-ant-..."
}

4. Download Stockfish (optional — chess only)

1. Go to https://stockfishchess.org/download/
2. Download the Windows x86-64 build
3. Extract the .exe file, for example to C:\stockfish\
4. Open config.json and set:

   {
     "stockfish_path": "C:\\stockfish\\stockfish-windows-x86-64.exe"
   }

If Stockfish is not found, chess analysis falls back to Claude Vision with a warning shown in the overlay.

---

Running

Important: Run as Administrator for global hotkey registration.

python main.py

First run: A dialog asks you to draw a capture region (click-drag on screen). Press Escape or click Cancel to use full-screen capture instead.

---

Usage

Action	Effect
Press F9	Capture screen → analyse → show recommendation
Drag the overlay	Repositions it (position is saved)
Click — button	Minimises overlay to a thin title bar
Click + button	Restores full overlay
Ctrl+C in terminal	Quit

---

Configuration (config.json)

Key	Default	Description
anthropic_api_key	""	API key (env var takes precedence)
hotkey	"F9"	Global capture hotkey
capture_region	null	Saved region {x,y,width,height} or null for full screen
stockfish_path	"C:\\stockfish\\stockfish-windows-x86-64.exe"	Absolute path to Stockfish binary
overlay_x	50	Overlay left position (px)
overlay_y	50	Overlay top position (px)
overlay_width	380	Overlay width (px)
overlay_height	220	Overlay height (px)
api_timeout_seconds	30	Claude API timeout

---

Testing individual modules

Each module can be run standalone:

# Verify config loads correctly
python config.py

# Capture screen to JPEG
python capture.py                        # → test_capture.jpg

# Interactively select capture region
python capture.py --select

# Detect game in a saved screenshot
python game_detector.py test_capture.jpg

# Analyse a chess screenshot
python analyzers/chess_analyzer.py test_capture.jpg

# Analyse a poker hand (uses synthetic data)
python analyzers/poker_analyzer.py

# Analyse any other game screenshot
python analyzers/generic_analyzer.py test_capture.jpg

# Preview overlay with demo data (no API key needed)
python overlay.py

---

Troubleshooting

Problem	Solution
F9 does nothing	Run main.py as Administrator
"ANTHROPIC_API_KEY not set"	Set env var or add to config.json
"Analysis timeout"	Increase api_timeout_seconds in config or check internet connection
Stockfish warning in overlay	Verify stockfish_path in config points to the .exe
Black overlay / no transparency	Ensure your GPU driver supports transparent windows

---

Project structure

gameadvisor/
├── main.py                  Entry point
├── capture.py               Screen capture + preprocessing
├── game_detector.py         Claude Vision game identification
├── overlay.py               PyQt6 transparent overlay UI
├── config.py                Configuration loader
├── analyzers/
│   ├── chess_analyzer.py    Stockfish + Claude chess analysis
│   ├── poker_analyzer.py    treys + Claude poker analysis
│   └── generic_analyzer.py  Claude Vision generic advice
├── config.json              Auto-generated on first run
├── requirements.txt
├── CLAUDE.md                Project context for Claude Code sessions
└── README.md

---

Privacy

Screenshots are sent to the Anthropic API over HTTPS and processed according to Anthropic's privacy policy. No data is stored locally beyond config.json.