Skip to main content
Glama

Balatro Agent

English | 简体中文

Let AI take the next run of Balatro.

A tool-capable AI uses local MCP tools to read player-visible information, choose and execute game actions, and save and reuse what it learns.

For Windows x64 · Steam Balatro · Codex desktop. The launcher and play activity window support English and Chinese.

Gold Stake clear

GPT-6.1 Sol has cleared Gold Stake using Balatro Agent. Watch the 26-second gameplay excerpt below (waiting periods sped up).

https://github.com/user-attachments/assets/fbc3b384-bd33-472a-82f0-dbf9969bc187

Related MCP server: local-game-mcp

Download and play

  1. Download the v1.4.0 project ZIP and extract it to a permanent folder. Keep the whole folder. Install the Steam edition of Balatro and sign in to Codex; close the game normally before installation or updates.

  2. Open Balatro Agent.exe and wait for Ready. It finds the project and game, prepares dependencies, backs up and installs the Mods, and configures MCP. No separate Python installation is needed.

  3. Choose Deck and Stake / mode, then click Start in Codex. When Codex supports the project link, it opens a project chat with the prompt filled in. Review and send the prompt in Codex to begin. The launcher closes after successfully dispatching the opening request.

If the project link does not open, reopen the launcher and use Copy play prompt. Paste it into a local Codex chat with the balatro-agent tools loaded. Both paths use the same short prompt with the actual project path, your selections and a play-rules file reference, so you do not need to select the project folder first. If tools are missing after setup, reload MCP or reopen Codex.

The launcher follows the Windows display language by default; use Language / 语言 to switch. You can close the launcher after sending the prompt. Keep the project folder.

If an earlier action is unconfirmed, its receipt is missing, or a checkpoint is damaged, normally close Balatro and click Abandon session / prepare on the launcher's error page. Old records stay preserved and old actions are never replayed. You can start again after preparation; reopening the launcher also resumes an interrupted archive. Recovery details

Test other models with CC Switch

Use CC Switch to configure other model providers in Codex and continue using this project's local MCP tools and Balatro Agent.exe. DeepSeek V4.1 Flash has been successfully connected through CC Switch and used to play this project.

Live play activity

An MCP game launch opens an independent activity window. Its HH:mm:ss timeline shows stage changes, short decisions, plan updates, action results, and experience saves. It displays the model's submitted rationale and plans.

Close the window at any time without interrupting play; double-click Balatro Status.exe to reopen it. The command Balatro Agent.exe --monitor also works. How it works and measured overhead

Each run's activity is automatically saved under runs/live/activity/by-run/. Normal results and post-run experience saves stay with that run.

Decks and stakes

The default is Red Deck / White Stake. Choose from 15 original decks; the selected deck must be visibly unlocked. After you send the play prompt, the AI first opens or shows the game, then checks the connection.

Stake / mode

Behavior

White, Red, Green, Black, Blue, Purple, Orange, Gold

One run at the selected stake

Highest stake

One run at the highest unlocked stake for that deck

Climb mode

Start at that deck's highest unlocked stake; retry normal losses, advance one stake after a verified win, and continue until beating Gold or you ask to stop

Climb mode reports and reviews each run before continuing.

Results and experience

Each completed run returns a brief report: actual deck / stake · win or loss · ante / round · elapsed time · experience update status.

After a single run or a completed climb, the game stays on the results screen with its window open. A climb continues after each run's report.

The AI reads the general guide before playing and other topics as needed. Both source baselines and local experience keep one current.md per topic; local updates amend and atomically replace that same file. Local experience takes priority and stays in runs/local-experience/.

More information

Setup and recovery · English support · Play rules · Verification evidence · Changelog

License

Self-authored code, documentation, and experience use the MIT License. Third-party licenses are listed in NOTICE.

Available Tools

12 tools
actA
DestructiveIdempotent

Submit one native action bound to current observation_id, unique action_id, short reason and actual experience_refs. For the bilingual activity window, reason may use '[zh-CN]Chinese rationale [en]English rationale' (replace placeholders with one concise equivalent sentence in each language, no internal reasoning); plain text remains valid. parameters: select={region,positions}; reorder={region,order}; blind={blind_slot}; buy/sell/use/take={region,position}; select_setup_option={kind:deck or stake,position}; play/discard may use {positions:[complete selection]} with positions-v1, or {} for already selected cards; others={}. native-target-v1 clicks the actual target/button; select consumable hand targets separately. Pack Tarot/Planet/Spectral immediate use is use; select_pack_card takes playing cards/Jokers or explicitly enabled consumables. Choose current visible unlocked candidates; native settings only. Random non-challenge. Identical IDs query, changed content rejects. AWAITING_INPUT: observe, close each native prompt once, query original navigation. Service UNKNOWN: pause gameplay, query the original ID and observe; continue local diagnosis, repair and isolated verification under maintenance policy, without replaying or bypassing pending records. Only an exact host approval-timeout receipt confirming no execution permits one identical client retry after original-ID and unchanged-state checks; see prompts/mcp-evidence.js.

Inputs: action (required), reason (required), action_id (required), parameters (required), +3 more. Returns: object

action_statusC
Read-onlyIdempotent

Query an action record in this game session and return filtered feedback; never replay it. Session change or missing records remains UNKNOWN; no cross-process exactly-once guarantee.

Inputs: action_id (required), view. Returns: object

calculateA
Read-onlyIdempotent

Explicit public numbers only. sum/difference/product/quotient/mean/median/variance_population take {values:[numbers]}; combination takes {n,k}; hypergeometric takes {population,successes,draws,min_successes,max_successes}, conditioned on uniform sampling without replacement. Up to 200 values/1000 population. Reject unknown/nonfinite values, zero divisors, extra fields and limits. No game/network reads, action recommendation, expressions or arbitrary code.

Inputs: inputs (required), operation (required). Returns: object

close_gameA
DestructiveIdempotent

Under an explicit user close request or standing authorization for necessary maintenance closure in docs/balatro-ai/maintenance.md: normally close the verified Balatro window and confirm exit, without force kill. Requires known current profile, latest observation_id, ready, normal results or idle main menu, and no pending actions. Reject active runs/UNKNOWN. 0-30 seconds; operation_id deduplicates. An uncertain response permits querying the identical operation only.

Inputs: operation_id (required), observation_id (required), timeout_s. Returns: object

healthA
Read-onlyIdempotent

Read connection, fixed versions, actual native profile and historical test-profile comparison. A profile mismatch is information only. Performs no game action.

Inputs: no named parameters. Returns: object

launch_gameA
Idempotent

Windows: verify Steam AppID 2379780, launch normally and wait for MCP. A new permitted launch also requests an independent bilingual activity window; closing or failing that viewer never controls gameplay. It displays public MCP summaries, submitted reason and run_plan, not internal model reasoning. If already running, verify/show its window; UNKNOWN allows only restoring that window. timeout_s is 0-30 seconds. operation_id is durably deduplicated; identical requests query only, without reopening the viewer. No game clicks, pending-action deletion, paths, commands or process IDs.

Inputs: operation_id (required), timeout_s. Returns: object

observeB
Read-onlyIdempotent

Read the player-visible state of the current identified native profile. Unknown actual profiles are reported. server_time is service wall-clock metadata outside the observation ID, usable for run timing, not pure model thinking time. No deck order, seeds or hidden card identity. Game names and descriptions retain their current game language.

Inputs: view. Returns: object

read_notesA
Read-onlyIdempotent

Actually read disk, local experience over read-only baseline; TEST is separate. Each experience topic has one current.md; revision is an update counter and older content is not retained for reading. Default strategy returns only actionable rules, conditions, counterexamples and confidence, plus short update references. It omits sources, historical facts, timestamps and write IDs. Explicit content/full views include audit information; full also returns the Chinese Markdown guide. Read EXP-GENERAL-GUIDE first, then relevant topics. Omitted IDs read all, [] reads none. index returns truncated previews/revision refs, not full reading or action evidence. query is literal, at most 80 characters; pages contain 20 entries, continue with next_offset. TEST retains historical reads. Existing note text keeps its original language.

Inputs: kind, view, query, offset, +2 more. Returns: object

recover_lost_sessionC
Idempotent

First query action_status and observe. Retire only after actual session change and confirmed record loss, with known current profile, fresh observation and ready. Requires a pending intent or, with all checkpoints clear, an unambiguous missing-record status previously delivered by this service in the lost session. A missing record alone never proves non-submission. The original remains UNKNOWN; RETIRED is not success or a normal loss. No game action, replay or save read. Identical recovery_id/parameters query the durable receipt. Reject live old sessions, stale observations or unknown profiles.

Inputs: action_id (required), recovery_id (required), observation_id (required). Returns: object

run_planA
Idempotent

Model-authored short run memory. read actually reads disk; omit other parameters. write requires latest observation_id, expected_revision(first 0), unique write_id and content{objective,priorities:[1-4],recheck_when:[1-4],experience_refs:[up to 6 fully read EXP-XXX@rN]}. For the bilingual activity window, objective and priorities[0] may each use '[zh-CN]Chinese summary [en]English equivalent' (replace placeholders with short matching summaries); plain text remains valid. At most 2000 UTF-8 bytes, 200 characters per item including both languages and tags. Only confirmed start_run/continue_run, actionable current run, no pending action. Same ID/content queries. Revise on material changes, read after compression. Run/profile/session changes invalidate reuse but retain history. No strategy generation or game action.

Inputs: mode, content, write_id, observation_id, +1 more. Returns: object

wait_until_readyA
Read-onlyIdempotent

Poll read-only until normal UI is actionable; default 10 seconds, maximum 30. Returns ready, timeout, disconnected or unsupported. Readiness alone does not confirm an action completed.

Inputs: view, timeout_s. Returns: object

write_noteB
Idempotent

Atomically replace the same local current.md, never upload or overwrite baseline. First local edit starts from the baseline current content, without copying old versions. Before amending, explicitly read content/full to preserve current strategy and audit fields. Submit the full updated content; it replaces rather than automatically merges text. 0 creates; updates require current expected_revision. The Chinese guide contains strategy only; sources, historical facts and compact hash receipts are separate audit metadata. Default strategy response omits audit fields. Receipts deduplicate write IDs without retaining old strategy content. Legacy local data requires the maintenance migration. TEST remains separate. content: sources[{run_id,steps}], facts, interpretation, conditions, counterexamples, confidence(low/medium/high), revision_reason. Formal run IDs start n5-, TEST starts test-. Model writes from actual feedback. Read back to verify.

Inputs: content (required), note_id (required), write_id (required), expected_revision (required), +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 12 tools

    Disambiguation4/5

    Tools cover distinct phases (session lifecycle, observation, action, notes, planning, math) and most purposes are clear. However, observe, action_status, and wait_until_ready all return status-like information, and recover_lost_session overlaps with action_status in record handling, creating minor confusion.

    Naming Consistency3/5

    All names use snake_case, but the set mixes single verbs (observe, act, calculate), noun phrases (health, action_status, run_plan), and verb_noun patterns (recover_lost_session, read_notes). This inconsistent structural convention is readable but not predictable.

    Tool Count5/5

    12 tools fit a complex game-agent domain that spans process control, game interaction, durable notes, run planning, and calculation. Each tool appears to earn its place without excessive redundancy.

    Completeness4/5

    The surface covers session lifecycle, observation, action submission, health, notes, run planning, and math. Gaps include no explicit profile-switching or action-listing tool, but these are minor workarounds within the described workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to play local Windows games through low-level keyboard/mouse input, screen capture, OCR, and per-game profiles for semantic actions.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Allows Codex desktop to control the Steam game Balatro via local STDIO MCP tools, exposing only constrained normal game actions without debugging or cheat capabilities.
      18
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to interact with running games in real time — introspecting game state, simulating keyboard and mouse input to actually play, capturing screenshots, executing Lua code, hot-reloading files, and receiving push notifications when state changes.
      8
      MIT