♟️ Cyber Chess Roast

A real-time chess AI commentary system powered by GitHub Copilot SDK. As you play, AI analyzes and comments on every move like a professional commentator.

✨ Features

🤖 Real-time AI Commentary: Professional game commentary using GitHub Copilot's advanced models (GPT-5, Claude Sonnet 4.5)
♟️ Complete Chess Engine: Full chess engine based on chess.js
🎨 Clean UI: Modern, responsive interface built with React + CSS
📡 Real-time Communication: Low-latency bidirectional communication via WebSocket
🎙️ Streaming Response: AI commentary displayed in real-time with typewriter effect
🔧 Custom Tools: Integrated professional tools for game state queries
📊 Game Analysis: Automatic identification of opening, middlegame, and endgame phases
🎬 Game Summary: Generate complete game summaries and reviews

🚀 Quick Start

Prerequisites

Node.js: >= 18.0.0
GitHub Copilot CLI: Installed and authenticated
GitHub Copilot Subscription: Valid paid subscription required

Install Copilot CLI

# Install via npm
npm install -g @github/copilot-cli

# Or use GitHub CLI extension
gh extension install github/gh-copilot

# Authenticate
copilot auth login

# Verify installation
copilot --version

Install Project Dependencies

npm install

Configure Environment Variables

# Copy example configuration
cp .env.example .env

# Edit .env file (optional)
# PORT=3000
# LOG_LEVEL=info

Start Development Server

# Start in development mode (concurrent frontend and backend)
npm run dev

# Or start separately
npm run dev:client  # Frontend dev server (Vite)
npm run dev:server  # Backend server (Node.js with tsx)

Application will run at:

Frontend: http://localhost:5173
Backend: http://localhost:3000
WebSocket: ws://localhost:3000

📖 User Guide

Basic Operations

Start Commentary: The AI commentator is ready when you open the app
Make Moves: Click a piece to select it, then click the target square to move
Real-time Commentary: After each move, AI provides real-time analysis and commentary
Generate Summary: After at least 5 moves, click "Summary" to get game review
Reset Game: Click "Reset" to start a new game

Interface Overview

┌─────────────────────────────────────────────────┐
│           ♟️ Cyber Chess Roast                 │
│          Real-time Chess AI Commentary          │
├─────────────────────────────────────────────────┤
│  Game Info   │        AI Commentary Panel       │
│  ┌─────────┐ │  ┌──────────────────────────┐   │
│  │ Round: 5 │ │  │ 🎤 AI Commentary ● Connected │   │
│  │ Moves: 9 │ │  │                          │   │
│  │ Phase:Mid│ │  │  [Streaming content...]  │   │
│  └─────────┘ │  │  ▊                       │   │
│              │  └──────────────────────────┘   │
│  ┌─────────┐ │                                 │
│  │         │ │                                 │
│  │  Board  │ │                                 │
│  │         │ │                                 │
│  └─────────┘ │                                 │
│              │                                 │
│  ┌─────────┐ ┌───────────┐                    │
│  │🔄 Reset  │ │📊 Summary │                    │
│  └─────────┘ └───────────┘                    │
└─────────────────────────────────────────────────┘

🏗️ Project Structure

cyber-chess-roast/
├── src/
│   ├── client/              # React frontend
│   │   ├── components/      # React components
│   │   │   ├── Chessboard.tsx
│   │   │   ├── Chessboard.css
│   │   │   ├── Commentary.tsx
│   │   │   └── Commentary.css
│   │   ├── hooks/           # React Hooks
│   │   │   ├── useChessGame.ts
│   │   │   ├── useStockfish.ts
│   │   │   └── useWebSocket.ts
│   │   ├── App.tsx
│   │   ├── App.css
│   │   ├── main.tsx
│   │   └── index.css
│   │
│   └── server/              # Node.js backend
│       ├── commentator.ts   # Copilot SDK integration
│       ├── websocket.ts     # WebSocket server
│       ├── types.ts         # TypeScript type definitions
│       └── index.ts         # Server entry point
│
├── public/                  # Static assets
├── index.html               # HTML template
├── package.json
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── .env.example
└── README.md

🔧 Tech Stack

Frontend

React 18: UI framework
TypeScript: Type safety
chess.js: Chess logic engine
Vite: Build tool
WebSocket Client: Real-time communication

Backend

Node.js: Runtime environment
TypeScript: Type safety
Express: Web framework
Socket.IO: WebSocket server
GitHub Copilot SDK: AI engine
chess.js: Game validation

📚 Core API Usage

GitHub Copilot SDK Initialization

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  logLevel: "warning",
  autoStart: true,
  autoRestart: true
});

await client.start();

Create Session

const session = await client.createSession({
  model: "gpt-4o",
  streaming: true,
  tools: [getGameStateTool, analyzePositionTool],
  systemMessage: {
    content: "You are a professional chess commentator..."
  }
});

Streaming Response

session.on((event) => {
  if (event.type === "assistant.message_delta") {
    // Handle incremental content
    process.stdout.write(event.data.deltaContent);
  }

  if (event.type === "session.idle") {
    // Commentary complete
    console.log("Commentary complete");
  }
});

await session.sendAndWait({ prompt: "Comment on this move..." });

🎯 Custom Tools

Project includes custom tools:

1. Get Game State Tool

const getGameStateTool = {
  name: "get_game_state",
  description: "Get current game state and move history",
  parameters: { type: "object", properties: {} },
  handler: async () => ({
    currentFEN: getCurrentFEN(),
    moveCount: getMoveCount(),
    lastMoves: getLastMoves(5),
    gamePhase: determinePhase()
  })
};

2. Analyze Position Tool

const analyzePositionTool = {
  name: "analyze_position",
  description: "Analyze current board position",
  parameters: {
    type: "object",
    properties: {
      depth: { type: "number", description: "Analysis depth" }
    }
  },
  handler: async ({ depth = 3 }) => ({
    evaluation: calculateEval(),
    threats: identifyThreats(),
    suggestions: getSuggestions()
  })
};

🔒 Security & Best Practices

Session Management: Automatic cleanup and session reuse
Error Handling: Comprehensive error catching and user feedback
Timeout Control: Prevent long-running operations
Resource Cleanup: Proper cleanup of Copilot client resources
Type Safety: Comprehensive TypeScript type definitions

📊 Performance Optimization

⚡ Streaming Response: Reduce time to first byte
🔄 Session Reuse: Avoid repeated initialization
📦 Code Splitting: Vite code splitting
🎨 CSS Optimization: Use CSS variables and minimal styles

🛠️ Development Guide

Debug Mode

# Enable verbose logging
LOG_LEVEL=debug npm run dev:server

# View Copilot CLI output
COPILOT_CLI_ARGS=--verbose npm run dev:server

Build for Production

# Build frontend
npm run build

# Start production server
npm start

Type Checking

# Check TypeScript types
npm run type-check

🐛 Troubleshooting

Copilot CLI Not Found

# Check if CLI is installed
copilot --version

# Check PATH environment variable
echo $PATH | grep copilot

# Manually specify path
echo "COPILOT_CLI_PATH=/path/to/copilot" >> .env

Authentication Issues

# Re-login
copilot auth logout
copilot auth login

# Check auth status
copilot auth status

WebSocket Connection Failed

Ensure backend server is running
Check firewall settings
Verify port is not in use

📝 Environment Variables

Variable	Default	Description
`PORT`	`3000`	Backend server port
`NODE_ENV`	`development`	Runtime environment
`COPILOT_CLI_PATH`	`copilot`	CLI executable path
`LOG_LEVEL`	`info`	Logging level

🤝 Contributing

Contributions are welcome! Feel free to submit Pull Requests.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

GitHub Copilot SDK - AI engine
chess.js - Chess logic
React - UI framework
Vite - Build tool

📞 Contact

For questions or suggestions, please submit an Issue.

Made with ❤️ for Chess and AI Enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
IMPLEMENTATION.md		IMPLEMENTATION.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
index.html		index.html
package.json		package.json
tsconfig.client.json		tsconfig.client.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

iwangbowen/cyber-chess-roast

Folders and files

Latest commit

History

Repository files navigation