See it play

A real run, nobody touching it.

The game on the right, the agent's reasoning on the left. The gameplay isn't edited: it reads the board, picks the blinds, plays the hands, and shops on its own.

The loop

How a frame of Balatro becomes a move.

1. Bridge

   A Steamodded mod (balatro_solver.lua) writes the game state every frame and polls balatro2_cmd.txt; bridge.py writes commands and reads the reply from balatro2_rsp.txt.

2. Read

   state_parser.py turns each response into a typed GameStateV2: deck, hand, jokers with sticker and edition flags, blind requirement, hand levels, dollars, ante.

3. Decide

   Different machinery for different parts of the game — and two policies you can pick between.

   • ♠Card playdeterministic search against the oracle, on a wall-clock deadline
   • ♥Shop & blinds--policy learned: a sim-trained 30-feature linear policy
   • ♦Shop, heuristic modeoracle marginal value + a Thompson-Sampling bandit over past runs

4. Act & record

   It plays the move and logs the decision with its reasons. Bandit weights update from finished runs; the learned policy's weights come from offline training in sim/.

The scoring brain

No synergy table. An oracle instead.

balatro_solver.py scores a hypothetical play exactly the way the game does — enhancements, editions, seals, per-card triggers, retriggers, held-card effects, joker ordering, xMult chains, Blueprint and Brainstorm copying. So a joker's worth is just score(board + candidate) − score(board). Photograph's combo with Hanging Chad shows up as a number, not as a rule someone remembered to encode. There is no hand-written synergy table anywhere in the project, and there should never be one.

In the deployed shop path, that marginal is a percentage gain against a representative hand for the build being committed to. It buys at +18%, drops to +8% while the board owns no scoring joker at all, and needs a 45% margin to sell something already on board — 15% if the swap is a flat board's first xMult.

The older heuristic policy scores each joker 0–100 from eight independent reads of the board, buying above 50 and committing above 75. The bars are each component's share of that range:

• ts0–40 · Thompson-Sampling signal from past runs
• power0–32 · raw xMult / mult / chips punch
• alignment0–30 · how often it actually triggers
• build target−15–25 · fit with the run's committed build
• deck fit0–15 · does the deck hold what it needs
• synergy−20–20 · pairings, and anti-pairings
• tempo0–10 · economy vs. scoring, by ante
• econ floor−30 · penalty for banking money with nothing that scores

Quickstart

Four steps to a hands-off run.

Linux · Steam/Proton · Python 3.11+ · Steamodded

# 1 · install Steamodded, then drop the mod in the Proton prefix's Mods folder
cp balatro_solver.lua "$PREFIX"/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/BalatRobot2/

# 2 · with Balatro running, confirm the bridge is live
python3 agent.py --check

# 3 · let it play (restart-on-death loop)
./run.sh

# 4 · curious what it's thinking?
python3 agent.py --explain

# measure something instead of guessing
python3 agent.py --eval --policy learned \
  --decks Blue --stakes Gold --episodes 1 --eval-out out.jsonl

Runtime is the Python standard library — no third-party packages. pytest only for the tests. --observe watches you play without sending commands; BALATRO_SHOP_DEBUG=1 plus analyze_shopdbg.py explains why an offer was refused.