Hearthstone AI Assistant: When Large Language Models Meet Card Strategy Games

This article introduces the open-source project 'Hearthstone Match Agent Assistant', an Electron-based desktop application. By parsing Hearthstone game logs and screenshots, it sends structured match data to large language models for strategic analysis. Its core design principles are 'read-only' and 'privacy-first'—it does not perform any automated operations, only provides decision-making references. The project is maintained by CuZaoo, with source code hosted on GitHub (link: https://github.com/CuZaoo/hearthstone-agent-assistant), and the update date is 2026-06-08.

With the development of Large Language Model (LLM) technology, AI has permeated various areas of digital life. In strategy card games, AI's potential is significant. As a classic digital card game, Hearthstone has complex strategic depth, requiring players to make optimal decisions during matches. This project combines LLM reasoning capabilities with game log parsing technology to provide players with intelligent strategic advice.

Log Parsing Engine

The project uses a handwritten state machine parser to process Hearthstone's Power.log, identifying events like TAG_CHANGE and SHOW_ENTITY. It supports multi-GB log processing, SHA1 deduplication, file rotation, and automatic discovery of session logs.

Game State Snapshot

Converts logs into GameStateSnapshot objects, which include structured information such as turn count, mana crystals, hand cards, and minions—providing a foundation for AI analysis.

Privacy Protection Mechanism

Data desensitization: Removes sensitive information (entity tags, player names, timestamps), only whitelisted data leaves the device.

Visual Verification System

Uses screenshots (used locally, not transmitted) and the dHash algorithm to verify card positions, comparing with the built-in card catalog to ensure data accuracy.

Multi-Model Compatibility

Supports over 9 mainstream AI service providers including OpenAI, DeepSeek, and Zhipu GLM, as well as local Ollama deployment—users can choose as needed.

Dual API Mode

Compatible with Responses API and Chat Completions API, adapting to different service provider specifications.

Structured Output

Prioritizes the json_schema format; if not supported, it falls back to json_object. Local validation ensures legitimacy.

Innovative Features

• Parallel multi-model queries: Configure multiple models for parallel requests, sort and fuse results by confidence.
• Adoption rate tracking: Compare turn state snapshots to automatically identify AI suggestions adopted by players, tracking the historical adoption rate of each model.

The application uses a three-window design:

1. Full Dashboard Window: Borderless and resizable, displaying detailed match analysis and AI suggestions.
2. Transparent Floating Window: Always on top, showing key information for quick reference.
3. Minimized Draggable Ball: Shrinks into a draggable ball, not interfering with the game view. Shortcuts: Ctrl+Shift+A to trigger analysis, Ctrl+Shift+O to toggle the floating window display.

Four-Layer Architecture

• core/: Pure business logic layer, no Electron/React dependencies, easy for testing and reuse.
• main/: Electron main process, responsible for window management, file access, and other native functions.
• renderer/: React UI layer, handling rendering and interaction.
• shared/: Shared type definitions and default configurations.

Encrypted Credential Storage

API keys are encrypted and stored via Electron safeStorage (using DPAPI on Windows), not saved in plain text.

Application scenarios:

• Novices: Learn card interactions and strategy selection.
• Advanced players: Get multi-angle strategic references to discover winning paths.
• Content creators/analysts: Use structured data for in-depth review and analysis. Project value: Demonstrates a compliant paradigm for combining LLMs with traditional games. The 'read-only' design ensures account security and fair competition.

This project represents a new model of AI application: enhancing rather than replacing human decision-making. Through technology, it converts game states into data understandable by AI, uses LLMs to provide suggestions, and leaves the final decision to the player. This model has broad prospects in the gaming field and also provides references for AI-assisted decision-making in other areas. In the future, there will be more innovative applications combining AI and human creativity.