♔ Prompt Chess

Play chess in your terminal while waiting for AI responses

A terminal-based chess game designed to run while you're waiting for AI coding agents (like OpenCode/Crush, Claude Code, etc.) to process your prompts. Turn dead wait time into productive chess practice!

chess-demo-1080p.mp4

✨ Features

• Two Game Modes: Classic (no timer) and Blitz (timed games)
• Built-in AI Opponent: Play as White against an approximately 1000 Elo engine
• Theme Matching: Dark, light, and classic themes that match your terminal
• Game Persistence: Games are automatically saved and restored between sessions
• Vim Motions: Intuitive arrow key navigation
• Blitz Timer: Configurable time controls with turn-based countdown
• Move Undo: Oops? Just press 'U' to undo

Installation

Reproducible Setup (Recommended)

# Clone or download this directory, then:
cd /path/to/prompt-chess
npm install

# Run interactive setup (writes config + wrapper)
./bin/setup-opencode-overlay

# Launch OpenCode with overlay wiring
./bin/opencode-with-chess

The setup wizard supports:

• --check (diagnostics only; no writes)
• --yes (accept defaults)
• --scope repo|global (plugin config scope)

Optional alias (so opencode always uses the wrapper from this repo):

# zsh/bash
alias opencode='/path/to/prompt-chess/bin/opencode-with-chess'

Add the alias to your ~/.zshrc or ~/.bashrc if you want it to persist.

Local Run

cd prompt-chess
npm install
npm start

Usage

# Classic mode (default)
prompt-chess

# 5-minute blitz
prompt-chess --mode blitz

# 3-minute blitz
prompt-chess -m blitz --time 3

# Light theme
prompt-chess --theme light

# Two-player local game (disable AI)
prompt-chess --opponent human

# All options
prompt-chess -m blitz -t dark -T 10 -o ai

# Overlay preset (for popup sessions)
prompt-chess --overlay

Command Line Options

Option	Short	Description	Default
--mode	-m	Game mode: classic or blitz	classic
--theme	-t	Theme: dark, light, or classic	dark
--time	-T	Blitz time in minutes	5
--opponent	-o	Opponent: ai or human	ai
--overlay	-	Overlay preset (blitz, 1 min, AI)	off
--help	-h	Show help	-

Keyboard Controls

Key	Action
↑↓←→	Move cursor
Enter	Select piece / Make move
Escape	Cancel selection
U	Undo last move
N	Start new game
Q	Quit

Integration with AI Coding Agents

OpenCode Integration (Ghostty + tmux Popup)

prompt-chess now includes a companion OpenCode plugin package that opens chess in a tmux popup while OpenCode is actively working and closes it when OpenCode goes idle.

Requirements:

• OpenCode running inside tmux
• tmux available in PATH
• Node.js 18+

Quick setup:

cd /path/to/prompt-chess
npm install
./bin/setup-opencode-overlay
./bin/opencode-with-chess

Manual check mode:

./bin/setup-opencode-overlay --check

Path handling:

• Uses XDG_CONFIG_HOME / XDG_CACHE_HOME when set.
• Falls back to ~/.config and ~/.cache on macOS/Linux.
• Falls back to temp directories if config/cache roots are not writable.
• Avoids hardcoded user paths by resolving repo and binaries dynamically.

Optional config file (~/.config/prompt-chess-opencode/config.json):

{
  "enabledByDefault": true,
  "repoAllowlist": [],
  "repoDenylist": []
}

Rule order:

• If repo matches repoDenylist: disabled
• Else if repoAllowlist is non-empty: only allowlisted repos enabled
• Else enabledByDefault applies

If OpenCode is not running in tmux, the plugin exits safely and does not open overlays. Implementation notes for setup internals are in tooling/ABOUT.md.

Nix / nix-darwin

This repo includes a minimal shell.nix for reproducible development:

nix-shell
./bin/setup-opencode-overlay --check

When Nix is detected, setup guidance prefers Nix-native commands first.

Crush / Sidecar Integration

If you prefer manual sidecar workflows:

Option 1: Shell Function (Recommended)

Add to your .bashrc, .zshrc, or .fishrc:

# Start chess when running crush
crush-with-chess() {
  # Open chess in a split tmux pane or new terminal
  tmux split-window -h "prompt-chess"
  crush "$@"
}

Option 2: Manual Launch

Simply open a second terminal/pane and run:

prompt-chess -m blitz -T 3

Then continue using Crush in your main terminal.

Option 3: Wrapper Script

Create a wrapper that launches both:

#!/bin/bash
# save as ~/bin/ai-with-chess

# Start chess in background terminal
alacritty -e prompt-chess -m blitz -T 5 &

# Run the AI agent
crush "$@"

VS Code / Other Editors

For editors with integrated terminals:

1. Open integrated terminal
2. Split the terminal
3. Run prompt-chess in one pane
4. Work in the other

🎨 Themes

Dark Theme

Default terminal-friendly dark theme with subtle square colors.

Light Theme

Clean light theme with beige/cream squares.

Classic Theme

Traditional black & white for that classic chess look.

Game Persistence

Games are automatically saved to ~/.prompt-chess/game-state.json after every move. If you quit and restart, your game will be restored!

Architecture

prompt-chess/
├── index.js                                  # Main CLI entrypoint
├── bin/setup-opencode-overlay                # interactive setup wizard
├── bin/opencode-with-chess                   # OpenCode launcher wrapper
├── bin/prompt-chess-overlay                  # tmux popup controller
├── tooling/                                  # setup/path detection utilities
├── opencode-plugin-prompt-chess-overlay/     # OpenCode plugin package
├── shell.nix                                 # minimal Nix dev shell
├── package.json                              # Dependencies and metadata
└── README.md                                 # This file

Tech Stack

• React: UI components and state management
• Ink: React-based terminal UI framework
• chess.js: Chess engine (move validation, game state)
• Chalk: Terminal colors and styling

Future Enhancements

• Strong AI levels (Stockfish integration)
• PGN export/import
• Opening book hints
• Move history display
• Multiple concurrent games
• Network multiplayer
• Better integration hooks (if Crush adds plugin API)

License

MIT