shellchess

Keyboard-driven TUI chess client for Lichess, built with Ink and chess.js.

shellchess is a terminal-first client for seeking and playing real games on Lichess without leaving your shell.

Features

• Board-first terminal layout that adapts to terminal resizing
• Lichess OAuth token setup with local config storage in ~/.shellchess/config.json
• Real-time board and clock sync from the Lichess Board API
• Keyboard navigation for piece selection and moves
• Promotion picker, resign, and draw offer actions

Requirements

• Node.js >=20
• A Lichess API token with board:play scope

Install

Published package name:

shellchess

Install globally:

npm install -g shellchess

Then run:

shellchess

You can also run it without a global install:

npx shellchess

First Run

On first launch, shellchess asks for a Lichess token and stores it at:

~/.shellchess/config.json

The file is written with 0600 permissions.

Create a token with:

• Scope: board:play
• Description: shellchess

Usage

shellchess

Current live matchmaking support is limited to the time controls accepted by the Lichess Board API matchmaking flow.

Controls

• Arrow keys: move cursor
• Enter: select piece / confirm move
• Esc: clear selection or cancel
• r: resign
• d: offer draw

Promotion mode:

• Left/Right: choose promotion piece
• Enter: confirm
• Esc: cancel

Local Setup

Install dependencies:

npm install

Run the app locally:

npm run dev

Run checks:

npm test
npm run typecheck
npm run build

Contributing

If you want to contribute:

1. Fork the repo.
2. Create a branch for your change.
3. Run the local checks before opening a PR.
4. Include screenshots or terminal recordings for UI/layout changes.

For UI work, there is also a local dev board so you do not need to start a live Lichess match every time:

npm run dev:board

Dev board shortcuts:

• Ctrl-R: reset current preset
• Ctrl-P: switch preset
• Ctrl-O: flip orientation

Notes

• The terminal font matters. Some fonts render filled Unicode black chess pieces poorly, so shellchess uses a stable glyph rendering strategy tuned for terminal compatibility.