Master Wong (王师父) - I Ching Oracle Powered by Claude AI

📋 Project Overview & Problem Statement

Challenge: The I Ching (易经) is one of the oldest divination texts in the world, with 64 hexagrams and complex casting mechanics. Most digital I Ching apps show generic definitions copied from translations — they don't connect the hexagram to the user's actual situation, and they don't explain what changing lines mean in context.

Solution: Master Wong (王师父) simulates a knowledgeable I Ching teacher who reads your situation, casts the hexagrams using the traditional three-coin method, and delivers a full interpretation in plain, conversational Mandarin Chinese — as if you're consulting a trusted friend who has studied the I Ching for decades. The app supports all three reading types: 单卦, 变卦, and 对比卦.

Key Benefits

Three-Coin Casting: Authentic three-coin I Ching casting mechanic — lines revealed one by one from the bottom up, with changing lines glowing red
AI-Recommended Reading Type: Master Wong reads your question and recommends the most appropriate type (single / changing / paired) before casting
Situation-Specific Interpretation: Every reading connects the hexagram symbols directly to your specific question — not a generic text block
Plain Mandarin: All output in conversational everyday Mandarin, not classical Chinese — no prior I Ching knowledge required
Follow-up Chat: Continue the conversation after the reading — ask for clarification, probe specific aspects, or share how the reading lands
Session Archive: Every reading saved as a timestamped JSON file including question, cast data, reading text, and chat history

🖥️ The Three Reading Types

单卦 — Single Hexagram

Best for simple questions, getting a feel for the day's energy, or when you need a quick direction. One hexagram, no changing lines. Clean and direct. Master Wong recommends this for focused, clear questions.

变卦 — Changing Hexagram

Best for situations in motion — a decision you're weighing, something that's shifting, or a complex situation. You get a primary hexagram (where you are now), changing lines (the pivot), and a second hexagram (where things are heading).

对比卦 — Paired Comparison

Best when you're torn between two specific options — two jobs, two paths, two approaches. The app casts a hexagram for each option and Master Wong compares the energy of both, giving his honest take on which direction looks stronger.

How a Session Works

Step 1: Type your question — the more context you give, the better the reading
Step 2: Master Wong recommends a reading type and explains why it fits your situation
Step 3: Click "开始占卜" to proceed, or switch to a different reading type
Step 4: Watch the three-coin casting — six lines appear one by one, red lines are changing lines
Step 5: Read Master Wong's full interpretation in plain Mandarin, connected to your specific question
Step 6: Ask follow-up questions in the chat panel — Master Wong stays in context of your hexagram

📊 Key Metrics

64

I Ching Hexagrams

3

Reading Types

6

Lines per Hexagram

3,000+

Years of I Ching History

🛠️ Tech Stack & Architecture

Node.js Express Claude Sonnet API ESM Modules Vanilla JS dotenv JSON Session Storage

Master Wong runs as a local Node.js + Express server. The hexagram casting logic (three-coin method, line generation, changing line detection) is handled entirely in JavaScript. The reading interpretation is generated by Claude Sonnet API with the hexagram data and the user's question as context. Sessions are saved as timestamped JSON files in the sessions/ folder.

Quick Start

# 1. Add your Anthropic API key to .env
ANTHROPIC_API_KEY=sk-ant-your-key-here

# 2. Double-click start.bat (Windows)
# Browser opens at http://localhost:3002

# 3. Type your question in Mandarin or English
# Master Wong responds in Mandarin
            

💡 Design Principles

Energy patterns, not predictions: Master Wong explicitly frames the I Ching as a mirror of the current situation's energy — not a fortune-telling tool. He always clarifies this in readings.
Traditional mechanics: The three-coin casting method is implemented faithfully. Lines are drawn probabilistically with correct weights for 老阳, 少阳, 少阴, 老阴 (changing and non-changing lines).
Accessible Mandarin: The system prompt instructs Claude to write in plain, everyday Mandarin without classical Chinese vocabulary. The readings are accessible to any Mandarin speaker regardless of I Ching background.
Warmth over authority: The persona is designed as a knowledgeable friend, not an infallible oracle. Master Wong is honest about uncertainty and encourages the user's own judgment.

☯ Master Wong · 王师父