chessplaza

A park, a few benches, a pond, and some deep-sea creature that has learned chess from listening to trash talk.

A virtual chess plaza: AI chess hustlers with distinct personalities, played by Claude agents over any UCI engine, in your terminal.

Think of Washington Square Park in NYC, or Dupont Circle in DC (but not any specific, exact place!) – places where chess hustlers gather to play, banter, and challenge passersby. This project brings that experience to your terminal, powered by LLMs.

Roadmap

Phase 1: Claude Agents epoch (shipped in 0.1.0)

• Chess hustler personas powered by Claude Agents SDK;
• Integration with UCI chess engines via chess-uci-mcp;
• Different hustler personalities: the trash-talker, the philosopher, the speed demon, the old master...
• Game/chat loop using Claude Agents SDK.

Phase 2: Experimentation epoch

• Basic voice output (Edge-TTS), complementing the text UI;
• Voice input (Whisper) to call out your moves (and words) instead of keyboard input;
• Switchable UI: command-line vs PySide-based (with proper chess board).

Phase 3: LangGraph/Gemini epoch

• Switching to Gemini, for LLM but specifically for advanced text-to-speech (each with distinct voice characteristics, intonations, etc);
• (Because of Gemini switch) Migrating from Claude Agents SDK to GenAI SDK (TTS, one-shot queries) and LangGraph (game/chat loop).

Prerequisites

• Claude Code authenticated (install), or ANTHROPIC_API_KEY environment variable;
• uv package manager (install);
• Stockfish or another UCI chess engine (download).

Usage

# Via uvx (PyPI release)
uvx "chessplaza[voice]" /usr/local/bin/stockfish

# Via uvx (latest from GitHub)
uvx --from "git+https://github.com/AnglerfishChess/chessplaza[voice]" chessplaza /usr/local/bin/stockfish

# From source
git clone https://github.com/AnglerfishChess/chessplaza.git
cd chessplaza
uv run chessplaza /usr/local/bin/stockfish

Options (work with any launch method):

• --voice / -v - enable text-to-speech
• --language <lang> / -l <lang> - play in a different language (e.g., Spanish, Russian)
• --use-github-deps - use bleeding-edge GitHub versions of dependencies (unstable, for development)

Development setup

git clone https://github.com/AnglerfishChess/chessplaza.git
cd chessplaza
uv sync --extra voice
uv run chessplaza /usr/local/bin/stockfish

Building Redistributables

PyInstaller is included in dev dependencies for building standalone apps. Full build instructions coming soon.

Troubleshooting

macOS: Microphone not working (voice input)

If voice input records silence or doesn't work, your terminal app likely lacks microphone permissions.

Fix:

1. Open System Settings → Privacy & Security → Microphone
2. Find your terminal app (Terminal, iTerm2, VS Code, etc.) and enable it
3. If not listed, the app hasn't requested access yet – try restarting the app

Verify via command line:

# Check which apps have microphone access
tccutil list Microphone

Still not working? Reset permissions to trigger a fresh prompt:

# For Terminal.app
tccutil reset Microphone com.apple.Terminal

# For iTerm2
tccutil reset Microphone com.googlecode.iterm2

Related Projects

• chess-uci-mcp - MCP bridge to UCI chess engines
• esca - the MIT-licensed Rust/Python chess library: rules, position facts, PGN, opening books and names