Source Code

Mingli 命理

Multi-system divination skill: Western astrology (Placidus houses, precise aspects), Ba-Zi / Four Pillars (Ngu Hanh), numerology (LifePath + personal cycles), and I Ching (hexagram + SPARK). Delivered daily via Telegram cron or on-demand.

Modes

Mode	Description	Trigger
Setup	Register birth data, compute all charts	"set up my horoscope"
Daily	Automated 4-system horoscope via cron	Cron schedule
On-demand	Instant horoscope	"my horoscope", "horoscope now"
I Ching	Hexagram reading (random or manual)	"cast I Ching", "throw hexagram"
Manage	Pause/resume/change time	"pause horoscope", "change horoscope time"

Scripts

# Western natal chart (kerykeion — houses, aspects, nodes)
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/calculate-western-natal-chart-using-kerykeion.py \
  --date 2000-03-25 --time 12:00 --tz "Asia/Saigon" --lat 21.0245 --lon 105.84117 --name "User"

# Ba-Zi Four Pillars + Western zodiac
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/calculate-bazi.py \
  --date 1990-05-15 --time 14:30 --tz "Asia/Saigon"

# Planetary positions (astronomyapi.com fallback for transit data)
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/fetch-planetary-positions.py \
  --lat 10.8231 --lon 106.6297

# Numerology — LifePath, Birthday, Attitude, Challenges, Pinnacles, Personal cycles
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/calculate-numerology.py \
  --date 2000-03-25

# I Ching hexagram casting
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/cast-i-ching-hexagram.py --mode random
.claude/skills/.venv/bin/python3 .claude/skills/mingli/scripts/cast-i-ching-hexagram.py \
  --mode manual --upper Kan --lower Kun --moving 2,1

Setup Mode

Ask for: birth date (YYYY-MM-DD), birth time (HH:MM), birth city (lat/lon + timezone)
Ask for: Telegram chat ID, preferred delivery time + timezone
Run all calculation scripts: natal chart, Ba-Zi, numerology
Write results to ~/clawd/memory/horoscope-users.md (include lat/lon, LifePath number)
Create daily cron job
Confirm: Western sign + ASC + Ba-Zi Day Master + LifePath + delivery schedule

Daily Mode

Cron triggers 4 scripts → all JSON fed to LLM → compose multi-system horoscope → Telegram.

See references/horoscope-prompt-template.md for full agentTurn message.

On-Demand Mode

Trigger: "my horoscope", "horoscope now", "what's my horoscope today"

Same flow, inline (not isolated session). Includes daily I Ching hexagram.

I Ching Mode

Trigger: "cast I Ching", "throw hexagram", "que Kinh Dich"

Random cast: 3-coin method, cryptographic randomness
Manual input: User provides upper/lower trigrams + moving lines
Output: primary hexagram, moving lines, transformed hexagram, SPARK summary

Management Commands

Command	Action
"pause horoscope"	Disable cron job
"resume horoscope"	Enable cron job
"change horoscope time to 7am"	Update cron schedule
"remove horoscope"	Delete cron job + memory entry

Cron Delivery

One cron job per user: horoscope-daily-{username}

{
  "name": "horoscope-daily-{username}",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "0 {hour} * * *", "tz": "{timezone}" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "[prompt from references/horoscope-prompt-template.md]",
    "model": "claude-sonnet-4-20250514",
    "timeoutSeconds": 180,
    "deliver": true,
    "channel": "telegram",
    "to": "{telegram_chat_id}"
  },
  "isolation": { "postToMainPrefix": "Horoscope delivered", "postToMainMode": "summary" }
}

State Tracking

File: state/users.json — maps usernames to cron job IDs.

Error Handling

kerykeion fails: Fallback to fetch-planetary-positions.py (API-based, no houses)
API down: LLM generates horoscope from zodiac knowledge only
Memory missing: Prompt user to run setup first
I Ching data missing: Generate hexagram from embedded trigram math only

References

references/astronomyapi-reference.md - API auth + endpoints
references/zodiac-reference.md - Western + Chinese zodiac tables, stems, branches
references/horoscope-prompt-template.md - LLM prompt for daily generation
references/i-ching-64-hexagrams.json - 64 hexagrams with Chinese/Vietnamese names

Dependencies

kerykeion (pip) — natal chart, houses, aspects. Install: pip install kerykeion
astronomyapi.com — env: ASTRONOMY_APP_ID, ASTRONOMY_APP_SECRET
All other scripts: Python stdlib only