Metadata-Version: 2.4
Name: sideboard
Version: 0.2.0
Summary: Chess in your terminal. Play against Chesster while your coding agent thinks.
Author: Zach Applegate
License-Expression: MIT
License-File: LICENSE
Keywords: chess,claude-code,idle-game,terminal,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0
Requires-Dist: python-chess>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sideboard

**Play chess against Chesster, inline in [Claude Code](https://docs.anthropic.com/en/docs/claude-code).**

```
    a   b   c   d   e   f   g   h
  ┌───┬───┬───┬───┬───┬───┬───┬───┐
8 │ ♖ │ ♘ │ ♗ │ ♕ │ ♔ │ ♗ │ ♘ │ ♖ │ 8
  ├───┼───┼───┼───┼───┼───┼───┼───┤
7 │ ♙ │ ♙ │ ♙ │ ♙ │ ♙ │ ♙ │ ♙ │ ♙ │ 7
  ├───┼───┼───┼───┼───┼───┼───┼───┤
6 │   │   │   │   │   │ ♘ │   │   │ 6
  ├───┼───┼───┼───┼───┼───┼───┼───┤
5 │   │   │   │   │   │   │   │   │ 5
  ├───┼───┼───┼───┼───┼───┼───┼───┤
4 │   │   │   │   │ ♟ │   │   │   │ 4
  ├───┼───┼───┼───┼───┼───┼───┼───┤
3 │   │   │   │   │   │   │   │   │ 3
  ├───┼───┼───┼───┼───┼───┼───┼───┤
2 │ ♟ │ ♟ │ ♟ │ ♟ │   │ ♟ │ ♟ │ ♟ │ 2
  ├───┼───┼───┼───┼───┼───┼───┼───┤
1 │ ♜ │ ♞ │ ♝ │ ♛ │ ♚ │ ♝ │ ♞ │ ♜ │ 1
  └───┴───┴───┴───┴───┴───┴───┴───┘
    a   b   c   d   e   f   g   h

Chesster: Alekhine's Defense — bold of you to invite the bayonet.
```

A chess game that lives inside your Claude Code conversation, for when the coding agent is grinding through a slow build.

## Install (Claude Code)

You'll need [uv](https://github.com/astral-sh/uv) on your `PATH` — the MCP server runs via `uvx`. Install with `brew install uv` if you don't have it.

In Claude Code:

```
/plugin marketplace add zappleg8/sideboard
/plugin install sideboard@sideboard
```

That's it. No pip, no shell config, no daemons.

## Play

```
/sideboard:play             # start or resume a game
/sideboard:play e4          # make a move (SAN: e4, Nf3, O-O, Bxe5, e8=Q)
/sideboard:board            # re-render the current state silently
/sideboard:resign           # resign and archive the PGN
```

One global game, persisted at `~/.sideboard/`. Quit Claude Code, come back tomorrow, the position is still there.

## Standalone CLI (no Claude Code)

If you'd rather play in a regular terminal:

```bash
pip install sideboard
sideboard                          # new game vs Chesster
sideboard --difficulty casual      # beginner-friendly
sideboard --difficulty shark       # bring your A-game
sideboard resume                   # pick up where you left off
sideboard stats                    # your record vs Chesster
```

Terminal mode renders a colored Rich-styled board with proper chess glyphs.

## How It Works

A small Claude Code plugin packages three pieces:

- A **slash-command skill** (`/sideboard:play`) that tells Claude to drive the game.
- An **MCP server** (`sideboard-mcp`, launched via `uvx`) that exposes the chess engine and game state as tools (`new_game`, `make_move`, `engine_response`, `get_state`, `resign`, `get_stats`).
- The **engine** is local Python — minimax with alpha-beta pruning, piece-square tables, and a curated Chesster quip pool that reacts to captures, checks, blunders, and brilliancies.

Each move is two MCP calls: `make_move` applies your move and returns the engine's top three candidates plus a Chesster quip; `engine_response` plays whichever candidate Claude picks. The board renders in the conversation as a fenced code block.

## Difficulty

| Level | Search depth | Behavior |
|---|---|---|
| `casual` | 2 ply | Occasionally picks an off-best move for variety |
| `club` | 3 ply | Default — solid, beatable |
| `shark` | 4 ply + quiescence | Sees tactics; will hurt you |

## Dependencies

- [python-chess](https://python-chess.readthedocs.io/) — board state, move legality, PGN export
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — Claude Code plugin server
- [Rich](https://rich.readthedocs.io/) — only for the standalone terminal CLI

## License

MIT
