The Bone Cracks, the Model Reads: Audited Divination for AI Agents

Sabla Nur — Sun, 23 Aug 2026 15:33:52 +0000

Three thousand years ago, Shang kings carved their divinations into bone — the first auditable record of an oracle at work. Oraclebone brings the same discipline to AI agents: audited scripts produce the draw, the hexagram, the pillars; the model only interprets what it is given. It never invents the result.

The problem: AI divination is hallucination with extra steps

Ask almost any chatbot for a tarot reading and it will happily "draw" three cards from its imagination. Ask it for an I Ching hexagram and it will generate one — sometimes a hexagram that doesn't even exist in the 64. Ask for your Bazi pillars and it will compute a year pillar from a lunar new year when the traditional system uses lichun (the solar term). These aren't edge cases; they're the default behavior of a language model doing divination.

For a practice whose entire value proposition is symbolic reflection on a given result, letting the model invent the result is catastrophic. The reading might be soothing, but it's not about anything. You can't audit it, reproduce it, or share it.

Oraclebone (GitHub · PyPI) is my attempt to fix that — a small, open-source toolkit that splits divination into two auditable jobs:

A local script produces the card draw, hexagram, or pillar set, using system entropy by default (or a user-supplied seed for reproducible demos).
The AI agent interprets that JSON output, inside documented safety boundaries.

The model never generates the divination result. It reads one.

What's inside

Four divination systems, one discipline:

System	What it does	Notes
Tarot	Draws cards for reflection, decisions, creative blocks	Major/minor arcana, upright/reversed, spreads
I Ching (易经)	Casts six-line hexagrams with primary + resulting hexagram	Coins or yarrow-stalk method; 卦辭/爻辭 classical texts included
Xiao Liu Ren (小六壬)	Casts from lunar-style numbers or Gregorian time	Traditional three-step palace count
Bazi (四柱八字)	Four Pillars chart from a birth datetime	True solar time correction, 大运 cycles, lunar-python engine

Three interfaces, same engine:

MCP server (uvx oraclebone-mcp) — zero-dependency, JSON-RPC 2.0 over stdio. Five tools: tarot_draw, iching_cast, xiaoliuren_cast, bazi_cast, interpretation_template. Mounts in Claude Desktop, Codex, Cursor, Continue, any MCP host.
CLI (oraclebone / legacy ai-divination) — oraclebone tarot --spread three-card --reversals, outputs JSON.
Agent skills — self-contained skill folders with adapters for Claude (claude.yaml), OpenAI/Codex (openai.yaml), Gemini (gemini.yaml), Cursor (cursor.mdc). Install with one line: curl -fsSL https://raw.githubusercontent.com/sapuyou45-bit/oraclebone/main/install.sh | bash.

Every JSON output carries audit metadata: method, seed (or null for entropy), warnings for approximate modes, and per-system provenance. The docs site (sapuyou45-bit.github.io/oraclebone) ships in six languages with a live in-browser demo.

Why "audited" isn't just branding: the correctness audit

Here's the part I'm proudest of. In v8.2.0 I ran a correctness audit against traditional references and found two real bugs:

1. Xiao Liu Ren off-by-one. The traditional method counts three steps — month from the first palace, day from the month's palace, hour from the day's palace — where each step counts its starting palace as one. The original implementation used ((month + day + hour - 2) % 6), which landed every cast one palace too late. Lunar month 1 / day 1 / hour Zi returned 留连 (Liú Lián) instead of 大安 (Dà'ān). Fixed with ((month + day + hour - 3) % 6) + 1 and anchored test cases against known traditional results.

2. Bazi zodiac boundary. Births between lichun and lunar new year produced contradictory output: year pillar 丙午 ("Horse") but shengxiao "Snake". The zodiac is now derived from the year pillar's earthly branch, with the lunar-new-year convention preserved separately so both remain auditable.

These are exactly the bugs that a model-generated reading would never surface — because the model doesn't do arithmetic, it narrates arithmetic. When the script does the math, the math can be checked.

The safety boundary

Divination is symbolic reflection, not prediction. Oraclebone's shared policy refuses medical, legal, financial, or crisis advice, frames results as reflection, preserves user agency, and states uncertainty explicitly. Good readings connect claims to the generated result — nothing more.

Try it

# One command, no install:
uvx oraclebone-mcp

# Or install the package:
pip install oraclebone

# Or the CLI directly:
oraclebone tarot --spread three-card --reversals
oraclebone iching --method yarrow
oraclebone xiaoliuren --method numbers --month 3 --day 12 --hour 7
oraclebone bazi --datetime 1990-05-20T14:30:00

Or skip the terminal entirely: open the online demo.

Repo: github.com/sapuyou45-bit/oraclebone — star it if you want more systems (Zi Wei Dou Shu? Liu Yao? runes? — the roadmap is community-driven)
PyPI: pypi.org/project/oraclebone
License: MIT · Python: 3.9–3.12 · no runtime dependencies (bazi needs the optional lunar-python extra)