@elizaos/plugin-mysticism

Mystical divination engines for ElizaOS agents — Tarot, I Ching, and Astrology readings with progressive revelation, emotional attunement, and optional payment integration.

Overview

This plugin gives ElizaOS agents the ability to perform three classical divination systems as interactive, multi-turn conversations:

• Tarot — Full 78-card Rider-Waite deck with multiple spread layouts (Three Card, Celtic Cross, etc.), card-by-card progressive reveal, and positional interpretation.
• I Ching — Three-coin method hexagram casting with full 64-hexagram corpus, changing line detection, and transformed hexagram support.
• Astrology — Natal chart calculation from birth data with planetary positions, house placements, aspect detection, and sign-by-sign interpretation.

Each system follows a phased reading lifecycle: intake → casting → interpretation → synthesis → closing, allowing the agent to pace the experience naturally and respond to user feedback between revelations.

Installation

npm install @elizaos/plugin-mysticism@next
# or
bun add @elizaos/plugin-mysticism@next

Peer Dependencies

• @elizaos/core (v2.x)
• Optional @elizaos/plugin-form for shared FORM service intake flows

Quick Start

Add the plugin to your agent's character configuration:

{
  "plugins": ["@elizaos/plugin-mysticism"]
}

Or import and register it directly:

import { mysticismPlugin } from "@elizaos/plugin-mysticism";

// Add to your agent's plugin list
const character = {
  plugins: [mysticismPlugin],
};

Actions

Providers

Forms

REST API Routes

The plugin registers HTTP routes on the agent's API server:

Example: Start a Tarot Reading

curl -X POST http://localhost:3000/api/readings/tarot \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "user-uuid",
    "roomId": "room-uuid",
    "question": "What should I focus on this month?",
    "spreadId": "celtic_cross"
  }'

Example: Start an Astrology Reading

curl -X POST http://localhost:3000/api/readings/astrology \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "user-uuid",
    "roomId": "room-uuid",
    "birthYear": 1990,
    "birthMonth": 6,
    "birthDay": 15,
    "birthHour": 14,
    "birthMinute": 30,
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": -5
  }'

Configuration

Optional pricing parameters can be set via agentConfig.pluginParameters or environment variables:

When prices are set to 0, the payment actions (REQUEST_PAYMENT, CHECK_PAYMENT) are effectively no-ops and readings proceed without a payment gate.

Architecture

plugin-mysticism/
├── typescript/           # TypeScript implementation (published to npm)
│   ├── src/
│   │   ├── actions/      # Agent actions (tarot, iching, astrology, payment, followup)
│   │   ├── engines/      # Pure divination logic, no runtime dependencies
│   │   │   ├── tarot/    # 78-card deck, spreads, interpretation
│   │   │   ├── iching/   # 64 hexagrams, trigrams, coin casting
│   │   │   └── astrology/# Chart calculation, zodiac, aspects, houses
│   │   ├── forms/        # Intake and feedback form definitions
│   │   ├── providers/    # Context providers for the LLM
│   │   ├── routes/       # REST API endpoints
│   │   ├── services/     # MysticismService — session and state management
│   │   └── types.ts      # Shared type definitions
│   └── __tests__/        # Vitest test suite
├── python/               # Python implementation of divination engines
├── rust/                 # Rust implementation of divination engines
└── package.json          # Root package (monorepo orchestration)

Engine Design

The engines (TarotEngine, IChingEngine, AstrologyEngine) are pure computational modules with no ElizaOS runtime dependency. They operate on structured data (JSON card decks, hexagram tables, zodiac definitions) and return typed results. This makes them independently testable and reusable outside the plugin context.

Service Layer

MysticismService manages reading session lifecycle, tracks per-entity active sessions, handles progressive reveal state, records user feedback, detects crisis language (with severity tiers and appropriate referral messaging), and integrates with the payment flow.

Safety

The service includes built-in crisis detection that scans user input for indicators of distress. When detected, the agent pauses the reading and provides appropriate mental health resource referrals rather than continuing with potentially harmful mystical interpretations.

Development

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

# Type check
bun run typecheck

# Lint & format
bun run lint
bun run format

License

MIT