A terminal-based Contract Bridge app where you play as South with an AI partner at North and two AI opponents at East/West. All three AI players bid and play using Standard American Yellow Card (SAYC) conventions.
This app is targeted at people who don't have access to a local Bridge club, but want to practice and improve their skills
- Play the game start to finish without any additional hints/guidance and review it play-by-play in the library with an AI tutor
- Play the game with an in-game tutor to get guidance on the best bid/play for the current stage of the game.
- Activate a Monte Carlo sampling engine that predicts HCP card probabilities and distribution for hidden hands to improve your own intuition and card counting skills.
Note
These features are meant as a learning tool to build up the underlying skills. These tools will not be available in a real game at a club/tournament, so do not over rely on it to play the game.
This is not a bridge game engine or a hand solver -- see other projects like Ben or DDS for that. This uses Anthropic LLMs with tuned prompta for AI bidding and gameplay, so usual caveats with LLMs apply.
You will need:
- Rust 1.8+
- Anthropic Claude Code -- either the
claudeCLI installed or an API key
This app was built and tested only on macOS but it should work on linux with appropriate modifications to the commands below
brew install rust
cargo install --git https://github.com/rsmenon/bridgette.gitOn first run, Bridgette creates a config file at ~/.config/bridgette/settings.yaml. Set your API key there or export it as an environment variable:
export ANTHROPIC_API_KEY=sk-ant-...The settings file also lets you pick models for each seat and the tutor:
api:
provider: anthropic
api_key: "${ANTHROPIC_API_KEY}"
agents:
north:
model: claude-opus-4-6
east:
model: claude-opus-4-6
west:
model: claude-opus-4-6
review:
model: claude-opus-4-6
enabled: trueBackend auto-detection: if an API key is present, Bridgette uses the Anthropic API directly. Otherwise it looks for the claude CLI. If neither is available, it won't start.
| Key | Action |
|---|---|
| N | New game |
| L | Open game library |
| B | Toggle probabilities |
| T | Toggle tutor panel |
| ? | Help |
| Q | Quit |
| Arrow keys | Navigate hand / bid selector |
| Enter | Play card / place bid |
When N/S is declaring, you control both hands — South as declarer or dummy, and North as the other. East/West always play themselves.
The game engine is a standalone state machine that handles dealing, auction validation, trick-taking, and scoring independently of the AI layer. The agent system runs LLM calls in background threads so the UI stays responsive. Each AI turn gets up to 3 retries; if all fail, it falls back to a safe default (Pass during bidding, first legal card during play). Errors show up in the bottom-left panel so you can see what happened.
Prompts are structured with a system message containing the full SAYC reference, plus a turn-specific message with the hand, auction history, valid moves, and situational reminders. The engine keeps the AI honest — it can only make legal bids and play eligible cards.
The probability display (toggle with B) estimates where each hidden card likely lives. It works by reading the auction — each bid implies constraints on HCP and suit lengths per SAYC — then running thousands of random deals that satisfy those constraints and the cards already played. The fraction of deals where a given card lands with a given opponent is that card's displayed probability. For small endgame positions it switches to exact enumeration instead of sampling.
Games are saved as JSON in ~/.config/bridgette/data/. The review system reconstructs game state at any point by replaying the recorded bids and cards through the engine.
| Feature/Screen | Screenshot |
|---|---|
| Gameplay |  |
| Live Tutor |  |
| Estimate HCP Cards & Distribution |  |
| Library |  |
| Post-game review |  |