@guanxing1/plugin-elizaos

ElizaOS plugin for 观星 GuanXing — Chinese metaphysics AI tools.

Give any Eliza-powered AI agent the ability to perform BaZi (八字) analysis, Tarot readings, I-Ching divination, Feng Shui assessments, dream interpretation, and more.

Powered by GuanXing / HeartAI.

Installation

Install via the ElizaOS plugin registry:

elizaos plugins add @guanxing1/plugin-elizaos

Or install directly with your package manager:

npm install @guanxing1/plugin-elizaos
# or
bun add @guanxing1/plugin-elizaos

Configuration

1. Get an API Key

Sign up at heartai.zeabur.app and create a developer API key.

2. Environment Variables

Variable	Required	Description
GUANXING_API_KEY	Yes	Your GuanXing API key. Get one at heartai.zeabur.app/developer
GUANXING_API_URL	No	API base URL (default: https://heartai.zeabur.app)

Set them in your .env file:

GUANXING_API_KEY=gx_sk_your_key_here
# GUANXING_API_URL=https://heartai.zeabur.app  # optional

3. Add to Your Agent Character

{
  "name": "MyAgent",
  "plugins": ["@guanxing1/plugin-elizaos"],
  "settings": {
    "secrets": {
      "GUANXING_API_KEY": "gx_sk_your_key_here"
    }
  }
}

Actions

This plugin provides 10 actions for Chinese metaphysics and fortune-telling:

Action	Description
BAZI_ANALYSIS	Chinese Four Pillars of Destiny (八字命理) — birth chart analysis
DAILY_FORTUNE	Daily fortune forecast by zodiac sign (每日运势)
QIUQIAN	Temple fortune stick divination (求签问卦) — Guanyin or Guandi
TAROT_READING	Tarot card reading (塔罗占卜) — single, three-card, or Celtic Cross
DREAM_INTERPRET	Dream interpretation (周公解梦) with psychology insights
ALMANAC_LOOKUP	Chinese almanac / Huang Li (黄历) — auspicious dates & activities
FENGSHUI_ASSESSMENT	Feng Shui analysis (风水评估) for home, office, or shop
NAME_SCORE	Chinese name numerology scoring (姓名打分)
COMPATIBILITY_CHECK	Zodiac/birth date compatibility (缘分配对)
ZODIAC_READING	Zodiac sign deep analysis (星座解读)

Example Conversations

BaZi Analysis

User: Can you do a BaZi reading for someone born on 1990-06-15 at 2pm?
Agent: 八字 BaZi Analysis for 1990-06-15 at 14:00
       Four Pillars: 庚午 壬午 丁巳 丁未
       Day Master: 丁火
       Five Elements: 金: 1 | 木: 0 | 水: 1 | 火: 4 | 土: 2
       ...

Daily Fortune

User: What's my daily fortune? I'm a Leo.
Agent: 狮子座 — Today's Fortune
       Overall: ★★★★☆
       Career:  ★★★★★
       Lucky Color: Gold
       ...

Fortune Stick (求签)

User: Draw a fortune stick — should I change jobs?
Agent: 🏮 Fortune Stick #42 — 旧燕衔泥
       Grade: 中上
       ...

Tarot Reading

User: Do a three-card tarot spread about my relationship
Agent: 🃏 Tarot Reading — Past / Present / Future
       Card 1: The Lovers — Deep connection...
       Card 2: The Tower (Reversed) — Upheaval settling...
       Card 3: The Star — Hope and renewal ahead...

Dream Interpretation

User: I dreamed I was flying over an ocean and saw a golden dragon
Agent: 🌙 Dream Interpretation
       Symbols: flying, ocean, golden dragon
       ...

Chinese Almanac

User: Check the Chinese almanac for today
Agent: 📅 Chinese Almanac — Today
       Lunar Date: 二月十九
       Auspicious: 开业, 搬家, 签约
       Inauspicious: 动土, 安葬
       ...

Feng Shui

User: Check the feng shui of my south-facing home office
Agent: 🏡 Feng Shui Assessment — office
       Score: 72/100
       ...

Name Score

User: Score the name 张伟
Agent: 📝 Name Score — 张伟
       Total Score: 85/100
       ...

Compatibility

User: Check compatibility between Leo and Pisces
Agent: 💕 Compatibility Check
       狮子座 × 双鱼座
       Overall Score: 68/100
       Love:       ███████░░░ 75%
       ...

Zodiac Reading

User: Tell me about Scorpio's personality
Agent: ⭐ 天蝎座 Zodiac Reading — personality
       Element: Water
       Ruling Planet: Pluto
       Key Traits: Passionate, Determined, Mysterious
       ...

Screenshots

See the images/ folder for logo and banner assets.

Development

# Install dependencies
bun install

# Build
bun run build

# Watch mode
bun run dev

# Type check
bun run typecheck

API

This plugin connects to the GuanXing API (https://heartai.zeabur.app/api/v1/). All 10 endpoints are POST requests authenticated via Bearer token.

License

MIT