What is hearthstone-oracle CLAUDE.md?

Project instructions for hearthstone-oracle, a service that provides Hearthstone card data, strategy advice, and deck analysis. Hearthstone is a digital card game, and the instructions also describe its data source, storage, testing, and logging rules.

Understanding the service architecture, working with downloaded card data and its database, writing tests first, and checking the project before commits.

They give a coding agent the project context and important rules needed to change the service safely.

How gregario/hearthstone-oracle configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to gregario/hearthstone-oracle. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/gregario/hearthstone-oracle/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/gregario/hearthstone-oracle

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/gregario/hearthstone-oracle/claude-md/github.svg)](https://agentmods.dev/instructions/gregario/hearthstone-oracle/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/gregario/hearthstone-oracle/claude-md"><img src="https://agentmods.dev/badge/instructions/gregario/hearthstone-oracle/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/gregario/hearthstone-oracle/claude-md"><img src="https://agentmods.dev/badge/instructions/gregario/hearthstone-oracle/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 654 This file is loaded in full into every session.

When invoked 654 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00654	$0.00654
Opus 5.5	$0.00262	$0.00262
Sonnet 5.5	$0.00131	$0.00131
Haiku 4.5	$0.00065	$0.00065

Measured 2mo ago against content hash 53579b609f35, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

hearthstone-oracle CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 50 lines

How it starts

The opening of the file, as written. The whole thing — 50 lines — stays where its author put it; the contents beside it link to each section on GitHub.

hearthstone-oracle

MCP server for Hearthstone card data, strategy coaching, and deck analysis.

Stack Profiles

MCP stack profile: ../../stacks/mcp/
TypeScript stack profile: ../../stacks/typescript/

Read both stack profiles before writing any code.

Architecture

Runtime data: Downloads HearthstoneJSON card data on first run, stores in ~/.hearthstone-oracle/
Does NOT bundle card data in the npm package — data is fetched at runtime
Updates: Checks HearthstoneJSON for newer builds, downloads only if newer
Storage: SQLite via better-sqlite3 with FTS5 full-text search
Two layers: Layer 1 (card data from HearthstoneJSON) + Layer 2 (curated strategy knowledge)

Data Source

HearthstoneJSON (hearthstonejson.com) — HearthSim community project. Unrestricted use. Auto-extracted from game files.

Engineering

Uses Superpowers for engineering execution. Follow TDD workflow: write tests first, then implement.

Important

All logging via console.error() — never console.log() (corrupts stdio JSON-RPC)
In-memory database for tests: getDatabase(':memory:')
Run /mcp-qa before every commit — no exceptions

HearthstoneJSON dbfId drift

What it is. dbfIds (the integer IDs encoded inside Hearthstone deckstrings) are NOT stable across HearthstoneJSON snapshots. The same logical card can be assigned a new dbfId between data drops, and old dbfIds can be reused for unrelated cards. Examples observed during the deck-decode fix session:

Reno Jackson (LOE_011): 27228 → 2883 (with a Core reprint at 76314).
Tirion Fordring (EX1_383): 391 → 890. The legacy 391 now resolves to Perdition's Blade, a completely different card.
Stonetusk Boar (CS2_171): 604 → 648.

Why it happens. This is a property of how HearthstoneJSON extracts and re-emits the card database from game files — not a bug in our pipeline. We consume the snapshot as-is.

What we do about it.

Snapshot TTL: the data pipeline refreshes from HearthstoneJSON on a TTL so we converge on the latest dbfIds.
Fallback message: decode_deck returns a clear placeholder for any dbfId not present in the local snapshot ("possibly added in a recent expansion; refresh data to resolve"), with the dbfId surfaced for lookup.
Test fixtures: seed data uses dbfIds from a recent snapshot. When fixtures drift, refresh them rather than freezing on legacy IDs.

Read the full file on GitHub · 50 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2mo ago First seen · 50 lines · 654 tokens per session scan A 53579b609f35

Subscribe to this mod's changes

hearthstone-oracle CLAUDE.md is an instructions file published in the GitHub repository gregario/hearthstone-oracle (2 stars, last pushed 6mo ago), licensed MIT. It adds 654 tokens to every session, about $0.0026 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

hearthstone-oracle CLAUDE.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
hearthstone-oracle CLAUDE.mdgregario/hearthstone-oracle	Instructions file	2	6mo ago	MIT	A	654	Claude Code
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	9,719	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	yesterday	MIT	A	7,461	Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	yesterday	MIT	A	4,680	Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	5,516	GitHub Copilot
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	3,093	GitHub Copilot
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harness	Instructions file	274k	2d ago	MIT	A	4,313	Codex, OpenCode

hearthstone-oracle: Instructions file for Claude Code