pi-chess-extension

    ♟️  PI CHESS  ♟️
    ═══════════════
    
    ┌───┬───┬───┐
    │ ♜ │ ♞ │ ♝ │  ╭─────────────────╮
    ├───┼───┼───┤  │  Play chess     │
    │ ♟ │ ♟ │ ♟ │  │  against the    │
    ├───┼───┼───┤  │  LLM in pi!     │
    │ . │ . │ . │  ╰─────────────────╯
    └───┴───┴───┘

Play chess against the LLM in pi.

You control the White pieces, the LLM plays as Black.

Installation

From npm

pi install npm:pi-chess-extension

Or add to your ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-chess-extension"]
}

From GitHub

{
  "packages": ["git:github.com/sjha2048/pi-chess-extension"]
}

Local Development

git clone https://github.com/sjha2048/pi-chess-extension.git
cd pi-chess-extension
npm install
npm run build

Then add to ~/.pi/agent/settings.json:

{
  "extensions": ["/path/to/pi-chess-extension/dist/index.js"]
}

Usage

Start a new game

/chess

Optional: Start from a specific position with FEN:

/chess rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1

Resume a saved game

/chess-resume

How to Play

The game opens as an overlay above the chat. Two input modes available:

Cursor Mode (default)

• Arrow keys - Move the >< cursor around the board
• Enter - Select a piece (shows [] around it) or move to target square
• * - Legal move destinations are highlighted
• + - Cursor is on a legal move square (target position)
• Tab - Switch to text mode
• ESC - Cancel piece selection
• Q - Quit the game

Text Mode

• Tab - Switch from cursor mode
• Type move - Enter algebraic notation (e.g., e4, Nf3, O-O, exd5)
• Enter - Submit the move
• ESC - Clear input and return to cursor mode

Game Flow

1. Start game with /chess
2. Make your move as White (cursor or text mode)
3. The LLM automatically responds as Black using the make_chess_move tool
4. Continue alternating until checkmate, stalemate, or draw
5. Game state is saved automatically - resume anytime with /chess-resume

The make_chess_move Tool

This tool is automatically invoked when it's the LLM's turn (Black). You don't need to call it manually.

Parameters:

• move - Move in algebraic notation (e.g., "e5", "Nf6", "O-O")

Features

• Human vs LLM - You play White, LLM plays Black
• Dual input modes - Cursor navigation or algebraic notation
• Visual feedback - Cursor position, selected piece, legal moves all highlighted
• Move validation - Powered by chess.js
• State persistence - Games survive session restarts
• FEN support - Start from any position
• Immediate responses - Uses steer delivery for real-time gameplay during tasks

Visual Guide

♟ CHESS - You(White) vs LLM(Black)

[CURSOR MODE - Arrows=move, Enter=select, Tab=text]

 a  b  c  d  e  f  g  h
8 ♜  ♞  ♝  ♛  ♚  ♝  ♞  ♜ 8
7 ♟  ♟  ♟  ♟  ♟  ♟  ♟  ♟ 7
6 .  .  .  .  .  .  .  . 6
5 .  .  .  .  ♟  .  .  . 5
4 .  .  .  .  ♙  .  .  . 4
3 .  .  .  .  .  .  .  . 3
2 ♙  ♙ >♙< ♙  .  ♙  ♙  ♙ 2   <- >< cursor on e2
1 ♖  ♘  ♗  ♕  ♔  ♗  ♘  ♖ 1
 a  b  c  d  e  f  g  h

>< cursor  [] selected  * legal  + pos  Q=quit

Requirements

• pi-coding-agent >= 1.31.0
• Interactive mode (not compatible with -p print mode)

Development

npm install
npm run build    # Compile TypeScript
npm run check    # Type check only

License

MIT

Contributing

Issues and PRs welcome at https://github.com/sjha2048/pi-chess-extension