Meihua Yishu (梅花易數 / Plum Blossom Numerology / Plum Blossom I Ching) is a traditional Chinese I Ching divination method, attributed to Shao Yong (邵雍) of the Song Dynasty. This project provides a professional Meihua divination system as an AI Skill for Claude Code.
Also known as: 梅花易数 (Simplified Chinese), Mei Hua Yi Shu, Plum Blossom Oracle, 梅花心易
Prefer a web app? Try the hosted version at iyarrow.xyz — no Claude Code setup required.
Why Meihua Yishu?
A Decision-Making Framework, Not Fortune-Telling
Unlike popular misconceptions about divination, Meihua Yishu is a structured thinking tool rooted in 3,000 years of Chinese philosophical wisdom:
| Misconception | Reality |
|---------------|---------|
| "Predicts the future" | Analyzes present conditions and likely trajectories |
| "Superstition" | Systematic framework based on pattern recognition |
| "Magic" | Philosophical method for examining situations from multiple angles |
Why "not prediction" is backed by evidence, not modesty: two independent experiments
both found that computing 吉/凶 from structure or 五行 lands at ~50% (coin-flip) — this
project's own prediction-validation report
(五行生剋 = 50.6%) and the sibling iching project's verdict-word masking test. See
references/why-not-prediction.md. The hexagram is a 象 to
read in context (互/變/錯/綜), not a verdict to compute.
Benefits
🎯 Decision Clarity — When facing complex choices, the hexagram structure forces you to consider factors you might overlook
🔄 Multiple Perspectives — The Ti-Yong (体用) framework systematically examines self vs. environment, action vs. reaction
⏱️ Timing Awareness — The 應期 (Yingqi) system encourages thinking about when to act, not just what to do
🌊 Change Philosophy — Based on the I Ching principle that everything changes; helps accept uncertainty and plan adaptively
💭 Reflection Tool — The divination process creates space for introspection and deeper thinking about your situation
Who Uses It?
Entrepreneurs — For strategic timing and partnership decisions
Individuals — For major life choices (career, relationships, relocation)
Curious Minds — To explore Eastern philosophy and symbolic thinking
Developers — To integrate traditional wisdom into AI applications
The Meihua Advantage
Compared to other I Ching methods:
Faster — No coins or yarrow stalks needed; cast from time, numbers, or observation
More Intuitive — Trigram-based (8 symbols) rather than full hexagram memorization (64 symbols)
Contextual — Ti-Yong analysis relates directly to your specific situation
Practical — Clear auspicious/inauspicious framework with actionable insights
"The Yi does not predict fate — it reveals patterns. Understanding patterns empowers better choices."
Features
Casting Methods
Time-based Divination — Cast using current or specified time. Defaults to second-level precision (a modern extension) so repeated casts within the same 2-hour 時辰 no longer collide; traditional 時辰 precision remains available (NEW!)
Number-based Divination — Cast hexagrams using numbers
Sound-based Divination — Cast using the count of sounds heard
Color-based Divination — Cast based on colors corresponding to five elements
Measurement-based Divination — Cast using object dimensions
Direction-based Divination — Cast based on the direction of a person or object
Interpretation Functions
Ti-Yong Analysis — Interpret the relationship between Ti (体) and Yong (用) trigrams via two complementary lenses: five-element 生克 and Trigram-Virtue 卦德 (健/順/動/入/陷/麗/止/說). Sibling research found 卦德 has ~5× the explanatory power of five-elements; both are framed as reference lenses, never verdicts (NEW!)
Full Relational Field — Beyond 互卦 (nuclear) and 變卦 (changing), each cast now also shows 錯卦 (complement — the opposite face) and 綜卦 (inverse — the other party's view), so a hexagram is read as a 象 in context (NEW!)
Tongguan Mediation — Analyze five-element bridging to mitigate克 (controlling) relationships
64 Hexagrams Interpretation — Detailed explanations of hexagram and line texts
Changing Lines Derivation — Analyze the fortune of transformed hexagrams
Seasonal Strength (卦氣) — Determine Ti trigram strength based on season
Timing Prediction (應期) — Predict when events will manifest
Strategy Guidance (策略建議) — Data-driven advice on whether to stay, leave, wait, or change (NEW!)
Specialized Readings
18 Specific Readings — Marriage, illness, wealth, travel, and more
Ten Responses (十應) — Environmental sign analysis
Bagua Correspondences — Modern and traditional symbolic associations
Character Analysis (測字) — Fortune telling by analyzing Chinese characters
AI-Assisted Features
Photo Analysis — Upload photos for AI to analyze environmental signs
Environmental Sensing — Describe surrounding sounds, colors, people for enhanced readings
Easy way: Paste this URL in Claude Code and say "Please install this skill":
https://github.com/muyen/meihua-yishu
Manual way:
# Personal skills (works across all projects)
git clone https://github.com/muyen/meihua-yishu.git ~/.claude/skills/meihua-yishu
# Or for a specific project
git clone https://github.com/muyen/meihua-yishu.git .claude/skills/meihua-yishu
Once installed, mention divination keywords like "占卦", "起卦", or "meihua" — the skill will activate automatically.
ChatGPT Custom GPT
Create a new GPT at https://chatgpt.com/gpts/editor
Copy the entire content of SKILL.md into the Instructions field (must be < 8000 characters)
Upload all 10 files from references/ as Knowledge files
Set conversation starters: "幫我起卦", "占一卦", "測字"
Google Gemini Gems
Create a new Gem at https://gemini.google.com/gems
Copy the entire content of SKILL.md into the Instructions field
Upload all 10 files from references/ as Knowledge files (Gemini limit: 10 files)
Set suggested prompts: "幫我起卦", "占一卦", "測字"
Using the Python Tool
# Cast using current time — second precision by default (NEW)
python scripts/meihua_calc.py time
# Cast using current time — traditional 時辰 (2-hour) precision
python scripts/meihua_calc.py time-shichen
# Cast hexagram using two numbers
python scripts/meihua_calc.py num 6 8
# Cast hexagram using three numbers (third is changing line)
python scripts/meihua_calc.py num 6 8 3
Example output:
==================================================
📿 Meihua Yishu Divination Result
==================================================
【1. Calculation】
Year: 10
Month: 1
Day: 17
Hour: Hai (12)
【2. Primary Hexagram】
#49: Ze Huo Ge (Revolution)
Upper: Dui ☱
Lower: Li ☲
Binary: 011101
Line 4 changing
【3. Ti-Yong Analysis】
Ti Trigram: Li (lower) - Fire · 麗 (clinging)
Yong Trigram: Dui (upper) - Metal · 說 (joyous)
Five-element (reference): Ti controls Yong (Auspicious)
Trigram-Virtue (reference, stronger): You (Ti) tend toward "clinging/showing", the situation (Yong) is "joyous/pleasing" ...
【4. Mutual Hexagram (互卦)】
Qian Wei Tian (Heaven over Heaven)
【5. Transformed Hexagram (變卦)】
#17: Ze Lei Sui (Following)
Binary: 011001
【6. Complement (錯卦) — the opposite face】
Shan Shui Meng — flip every line; shows the side you didn't see
【7. Inverse (綜卦) — the other party's view】
Shui Huo Ji Ji — turn it upside down; see it from across the table
==================================================
Core Principles
Yi = Change (易 = 變)
The fundamental principle of I Ching is change. The purpose of divination is not just to predict fortune, but to guide optimal action:
Able to change = things flow (proactive adjustment, flow with circumstances)
Stuck in place = trouble (missing opportunities)
Every divination must include strategy guidance — telling the querent what to do next.
Early Heaven Bagua Numbers
Meihua Yishu uses Early Heaven Bagua Numbers:
| Trigram | Number | Element | Symbol |
|---------|--------|---------|--------|
| Qian (乾) | 1 | Metal | ☰ |
| Dui (兌) | 2 | Metal | ☱ |
| Li (離) | 3 | Fire | ☲ |
| Zhen (震) | 4 | Wood | ☳ |
| Xun (巽) | 5 | Wood | ☴ |
| Kan (坎) | 6 | Water | ☵ |
| Gen (艮) | 7 | Earth | ☶ |
| Kun (坤) | 8 | Earth | ☷ |
Ti-Yong Theory
Ti (体): The subject, self, the querent
Yong (用): The object, matter, external environment
Mutual Hexagram (互卦): The development process
Transformed Hexagram (變卦): The final outcome
Fortune Determination
| Situation | Fortune | Explanation |
|-----------|---------|-------------|
| Yong generates Ti | Very Auspicious | Gaining benefits, external assistance |
| Ti controls Yong | Auspicious | You control the situation, success likely |
| Ti-Yong in harmony | Auspicious | Same element, harmonious and smooth |
| Yong controls Ti | Inauspicious | Constrained by others, unfavorable |
| Ti generates Yong | Draining | Much effort, little return |
Tongguan Mediation (通關化解)
When Ti and Yong are in a controlling relationship, a "bridging" element in the Mutual or Transformed hexagram can mitigate the inauspicious outcome:
| Controlling Relationship | Bridging Element |
|--------------------------|------------------|
| Metal controls Wood | Water |
| Wood controls Earth | Fire |
| Earth controls Water | Metal |
| Water controls Fire | Wood |
| Fire controls Metal | Earth |
Divination Principles
No question, no divination — Don't divine without a specific question
No more than three times — Don't repeat divination for the same question more than three times
No movement, no divination — Don't divine without cause
Interpret with reason — Hexagrams must be interpreted in context
Decoding I Ching — Text-analysis research on I Ching patterns. Provides the 384-line database and the classical-text metrics (auspicious/inauspicious word density, text-embedding similarity) used in this skill's reference files. Note: these measure the language of the classical texts, not real-world outcome probabilities.
Contributing
Issues and Pull Requests are welcome!
☯️ The Yi has Taiji, which generates the Two Forms, which generate the Four Images, which generate the Eight Trigrams.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.
