# Checkmate
Native macOS chess practice and learning, built with AppKit and SwiftUI.
Offline Stockfish 19, 34 lessons with 5 practice activities, 82 puzzles and 710 Cedar recordings.
Lesson mini-games include computer opponents. Game review supports finished and unfinished games, PGN files and FEN positions.
```sh
brew install --cask xiaolai/tap/checkmate
```
Requires macOS 14 or later. One universal app supports Apple Silicon and Intel Macs. [Development](docs/development.md),
[release packaging](docs/releases.md), [changelog](CHANGELOG.md).
The voice coach is off until you choose Connect. The first time, Checkmate explains
what is sent to OpenAI, that it uses your ChatGPT plan through Codex, and that the
microphone is used while voice is connected; it connects only if you agree, and you
can choose there to connect it automatically at launch. At launch, Checkmate can
also start its private chess MCP broker, once Set up Codex has registered it.
Control these separately in Settings → Voice Coach and Settings → Connections. The
voice coach's Codex availability check runs at launch only after you have agreed
and set voice to connect on launch. While voice is connected, external MCP requests are refused with an explanation until voice disconnects.
Voice runs on your ChatGPT subscription: it asks Codex for its ChatGPT sign-in
(which Codex may keep in the keychain) and has Codex renew it when it is about to
expire; without an installed Codex it reads Codex's sign-in file, which it never
writes. It never uses an API key.
The coach automatically selects the newest compatible model from its supported stable list (currently GPT-Realtime-2.1 and GPT-Realtime-2). A silent check verifies reasoning effort and chess tools; the result is cached for this app session for up to 24 hours. Settings → Voice Coach → Check availability refreshes the selection. The selected model is shown in Settings and remains fixed throughout a conversation. Choose reasoning effort in Settings → Voice Coach;
Minimal is the default, with Low, Medium, High and Extra high available.
A change applies between responses without reconnecting; if the connected model
refuses an effort, Settings returns to the one in use.
In a guided game the coach gives one short idea after each of your moves, and
comments on Stockfish's move only for a check, capture, promotion or the end of
the game. Where macOS echo cancellation is available you can interrupt the coach
by speaking; otherwise press Stop. A reply that fails or takes too long ends that
reply, not the session. Voice that was connected reconnects when you return to
Practice or show the app again, and a long session renews itself between replies
before the provider's one-hour limit. Preview voice plays the voice selected in
Settings, even while the coach is using another. Settings → Usage counts narrated
segments heard as written, shown as text instead, and stopped.
For an external Codex companion, choose **Set up Codex** after installing in Applications (and again if you move the app) in Settings →
Connections, then start a new Codex task with `$checkmate-companion`.
In Settings → Lessons, choose a language and translate one lesson or the whole
course with your signed-in Codex account. Inspect the translated text, generate
and play a preview, then choose **Record / Resume**. Cedar is the default voice;
Marin is also available. Completed recordings play offline. A lesson uses English
until its selected language and voice have a complete recording set. You can
discard a translation to replace it without losing lesson progress.
Settings → Usage shows Checkmate's translation, recording, coaching and input
transcription activity. Provider credit and USD estimates appear when available;
they are not actual charges. Missing counters and voice subscription attribution
remain unknown. Account status is refreshed separately, and usage history can be
exported or cleared.
Original code and owner-authored course materials: GPL-3.0-or-later. Third-party
licenses retain their own terms; see [notices](THIRD_PARTY_NOTICES.md). Matching
Stockfish source and its reproducible build recipe are included in
`ThirdParty/Stockfish/`. Lesson audio is AI-generated.
## Uninstall
Before removing the app, choose **Remove Codex Setup…** in Settings → Connections if you
used Set up Codex; it removes Checkmate's Codex connection and its companion skill (a skill
you edited is kept). Then `brew uninstall --cask checkmate`, or drag Checkmate to the Trash.
Your progress, saved reviews, translated lessons, recordings and usage history stay in
`~/Library/Application Support/ai.xiaolai.checkmate`; `brew uninstall --zap --cask checkmate`
removes them and the companion skill. Microphone permission is listed under System Settings →
Privacy & Security → Microphone.
## Repository layout
The Swift package lives at the repository root. Run development commands from this directory.
- `Sources/` and `Tests/`: application, native MCP companion, and tests.
- `Artwork/`, `Content/`, and `ThirdParty/`: design assets, lesson scripts, and upstream source.
- `Tools/` and `scripts/`: content tooling, build verification, and release automation.
- `docs/`: development and release documentation.
- `companion/`: the Codex coaching skill.
Local builds, recordings, evidence, and private development notes are ignored by Git.