Astrology — Lunar Phase & Influence Analysis

Engine: Swiss Ephemeris (pyswisseph 2.10.3.2) + Pillow (PIL)

This skill calculates lunar phases and analyzes the Moon's influence on a person through multiple astrological lenses. It renders a chart with 2 wheels side-by-side (Moon phase + natal chart with transit Moon), 3-group horizontal legend below wheels, and a text analysis panel on the right.

🔬 Precision

All planetary positions are computed using the Swiss Ephemeris library (pyswisseph 2.10.3.2), based on NASA's JPL DE431 ephemerides. Planetary position accuracy: ~0.003°. House cusps: Placidus system via swe.houses_ex().

⚠️ Requirements

Architecture

lunar_analysis.py --json  →  JSON data (all lunar metrics)  →  draw_lunar.py  →  PNG image
         ↕
   lunar_analysis.py  →  text analysis output

lunar_analysis.py is the sole calculation engine. draw_lunar.py renders the chart by calling it via subprocess.

What This Skill Calculates

1. Current Moon Phase

The Moon's position relative to the Sun (elongation angle):
- 0° = New Moon (🌑) — conjunction
- 90° = First Quarter (🌓) — waxing
- 180° = Full Moon (🌕) — opposition
- 270° = Last Quarter (🌗) — waning
- Plus 4 intermediate phases (Crescent, Gibbous, etc.)

Also calculates: illumination %, distance from Earth (km), exact dates of nearest phases.

2. Transit Moon → Natal Moon (Personal Lunar Cycle)

The most important personal lunar metric. The transit Moon forms aspects to the natal Moon over a ~28-day cycle:

3. Personal Solar-Lunar Phase (Transit Moon → Natal Sun)

The Moon's position relative to the natal Sun defines a personal lunar month (~29.5 days):

4. Transit Moon Through Natal Houses

Shows which life area is emotionally activated:

5. Lunar Day (Tithi) — Vedic System

30 lunar days from New Moon to New Moon, each with specific energy:
- Day 1: New beginning, planning
- Day 14: Peak energy — best for starting anything
- Day 20: Eagle day — see the big picture
- Day 29: Difficult day, caution
- Day 30: Blessing, gratitude, cycle completion

6. Moon Speed Analysis

Moon's daily motion affects emotional processing:
- >14.5°/day: Very fast — quick events, less depth
- 13.5–14.5°: Fast — rapid emotional shifts
- 11.5–13.5°: Normal — balanced processing
- 10–11.5°: Slow — lingering feelings, deeper impact
- <10°/day: Very slow — prolonged emotional intensity

Also tracks approach to perigee (closer = stronger) or apogee (farther = weaker).

7. Transit Moon Aspects to All Natal Planets

Complete picture of how the transit Moon interacts with every natal planet — shows which psychological functions are emotionally activated.

Usage

Text Analysis (CLI)

# Analysis for today
python scripts/lunar_analysis.py 24.04.1983 07:00 Ижевск --lang ru --name "Алексей"

# Analysis for any specific date
python scripts/lunar_analysis.py 24.04.1983 07:00 Ижевск --target-date 05.06.2026 --lang ru

# English output
python scripts/lunar_analysis.py 24.04.1983 07:00 Ижевск --lang en

# JSON output (for renderers / AI)
python scripts/lunar_analysis.py 24.04.1983 07:00 Ижевск --target-date 05.06.2026 --json

Graphical Chart

# Chart for today (Russian)
python scripts/draw_lunar.py 24.04.1983 07:00 Ижевск --lang ru --name "Алексей"

# Chart for any specific date
python scripts/draw_lunar.py 24.04.1983 07:00 Ижевск --target-date 05.06.2026 --lang ru --name "Алексей"

# English
python scripts/draw_lunar.py 24.04.1983 07:00 Ижевск --target-date 05.06.2026 --lang en --name "Alexey"

CLI Arguments

JSON Output Format

{
  "name": "Алексей",
  "birth_date": "24.04.1983",
  "birth_time": "07:00",
  "birth_city": "Ижевск, Россия",
  "target_date": "05.06.2026",
  "moon_phase": {
    "name": "Waning Gibbous",
    "elongation": 236.33,
    "illumination": 77.7,
    "distance_au": 0.002669,
    "distance_km": 399206
  },
  "nearest_phases": {
    "New Moon": {"date": "15.06.2026", "days_diff": 9.6},
    "Full Moon": {"date": "31.05.2026", "days_diff": -5.1}
  },
  "lunar_day": {"number": 20, "meaning_ru": "День орла..."},
  "transit_moon": {"lon": 311.18, "sign": "Capricorn", "speed": 12.14},
  "transit_moon_to_natal_moon": {"aspect": "Sesquiquadrate", "orb": 0.91},
  "personal_phase": {"key": "last_quarter", "name_ru": "Персональная последняя четверть"},
  "transit_moon_house": {"house": 7, "title_ru": "Партнёрство, брак..."},
  "moon_speed": {"speed": 12.14, "description_ru": "Нормальная..."},
  "transit_moon_aspects": [
    {"transit": "Moon", "natal": "Sun", "aspect": "Square", "major": true, "orb": 7.6}
  ],
  "engine": "Swiss Ephemeris v20230604"
}

Image Layout (5760×2880 px)

+---------------------------+---------------------------+-------------------+
|                           |                           |                   |
|     ФАЗА ЛУНЫ             |     НАТАЛЬНОЕ КОЛЕСО      |   TEXT ANALYSIS   |
|     MOON PHASE WHEEL      |     NATAL CHART WHEEL     |   PANEL           |
|     (3400/2 = 1700 wide)  |     (1700 wide)           |   (2360×2880)     |
|                           |                           |                   |
|  - Phase circle           |  - Sign sectors (elements)|  - Moon phase     |
|  - Illumination % center  |  - House cusps (Placidus) |  - Nearest phases |
|  - Phase degree markers   |  - Natal planets (circles |  - Lunar day      |
|  - Current position       |    with letter codes)     |  - Moon aspects   |
|    indicator (yellow)     |  - Transit Moon (outer    |  - Personal phase |
|                           |    orbit, highlighted)    |  - House          |
|                           |  - ASC/MC lines           |  - Moon speed     |
|                           |  - Aspect lines (colored) |  - All aspects    |
|                           |                           |  - Conclusion     |
|                           |                           |                   |
+---------------------------+---------------------------+-------------------+

Legend (below wheels, 3 uniform-height groups side by side):
┌─────────────────┬─────────────────┬─────────────────┐
│  ПЛАНЕТЫ        │  АСПЕКТЫ        │  СТИХИИ         │
│  (PLANETS)      │  (ASPECTS)      │  (ELEMENTS)     │
│                 │                 │                 │
│  ♈ SU Sun      │  □ Conj          │  ■ Огонь        │
│  ♉ MO Moon     │  ✶ Sext          │  ■ Земля        │
│  ♊ ME Mercury  │  □ Sqr           │  ■ Воздух       │
│  ...            │  △ Trine         │  ■ Вода         │
│                 │  □ Qnc           │                 │
│                 │  ☍ Opp           │                 │
└─────────────────┴─────────────────┴─────────────────┘

• Wheels centered vertically in the image (cy=1440)
• Wheels radius: 640px each
• Legend: 3 groups of uniform height below wheels
• Left panel: 3400px (2 wheels × 1700px)
• Right panel: 2360px text interpretation

Font Handling

Two bundled fonts in scripts/:

Both are auto-copied to .ttf at runtime for Pillow compatibility.

Scripts Reference

AI Conclusion Workflow (for OpenClaw agents)

Step 1: python scripts/lunar_analysis.py <date> <time> <city> --json --target-date <date>
Step 2: AI analyzes JSON and writes enhanced conclusion to a JSON file
        (see AI Conclusion JSON Format below)
Step 3: python scripts/draw_lunar.py <date> <time> <city> --lang ru --name "Name" --conclusion <file.json>

When --conclusion is provided, the AI-generated text is used verbatim in the chart.
Each metric gets its own interpretation section (1–8), and the overall summary
is shown in section 9 (Conclusion). Without --conclusion, the script generates
built-in autonomous interpretations.

AI Conclusion JSON Format

The conclusion file must have metric keys at the top level (not nested under metrics).
Each metric contains an interpretation field (string, dict with description, or tuple).
The overall field contains the general summary for section 9.

{
  "overall": "General summary text for section 9...",
  "moon_phase": {
    "interpretation": {
      "name": "Waning Gibbous",
      "description": "Full interpretation text for section 1..."
    }
  },
  "nearest_phases": {
    "interpretation": "Interpretation text for section 2..."
  },
  "lunar_day": {
    "interpretation": "Interpretation text for section 3..."
  },
  "transit_moon_to_natal_moon": {
    "interpretation": "Interpretation text for section 4..."
  },
  "personal_phase": {
    "interpretation": ["Phase Name", "Interpretation text for section 5..."]
  },
  "transit_moon_house": {
    "interpretation": "Interpretation text for section 6..."
  },
  "moon_speed": {
    "interpretation": "Interpretation text for section 7..."
  },
  "transit_moon_aspects": {
    "interpretation": "Interpretation text for section 8..."
  }
}

Supported interpretation formats:
- dict with description key — used by autonomous mode
- tuple/list of [title, text] — used by autonomous mode for personal_phase
- string — plain text interpretation (AI mode)

The renderer (draw_text_panel) automatically detects the format and extracts
the text accordingly. AI mode shows full text without truncation; autonomous mode
limits text to keep the chart compact.

AI Workflow (for OpenClaw agents)

⚠️ ПРАВИЛО: ВСЕГДА предоставляй расширенную интерпретацию ИИ, когда это возможно.

Автономная интерпретация (встроенная в скрипт) — это fallback для CLI-использования. Когда скилл вызывается через OpenClaw агент, агент обязан проанализировать JSON и сгенерировать расширенную интерпретацию по всем метрикам. Это ключевое отличие качественного прогноза от шаблонного.

Step 1: python scripts/lunar_analysis.py <date> <time> <city> --json --target-date <date>
Step 2: AI analyzes JSON and provides extended interpretation for ALL metrics
Step 3: AI writes conclusion JSON file with overall summary
Step 4: python scripts/draw_lunar.py <date> <time> <city> --lang ru --name "Name" --conclusion <file.json>

Без шага 3-4 карта будет содержать только автономную (краткую) интерпретацию.

The AI should focus on:
- Personal New/Full Moon — most significant events
- Transit Moon house — which life area is emotionally active
- Transit Moon → Natal Moon aspect — emotional cycle phase
- Moon speed — depth vs. speed of emotional processing
- Lunar day meaning — Vedic tithi guidance
- Transit Moon aspects to all natal planets — detailed psychological analysis
- Overall synthesis — practical recommendations for the day

Encoding & Console Handling

Problem: Windows console (cmd/PowerShell) redirects stdout in cp1251/cp866, breaking UTF-8 output even with PYTHONIOENCODING=utf-8.

Solution: lunar_analysis.py supports --output file.json which writes JSON directly to a file via open(..., encoding='utf-8'), completely bypassing the console. draw_lunar.py uses this internally — it passes --output /tmp/lunar_analysis_tmp.json to the subprocess and reads the file directly.

For CLI users: Use --output when redirecting to files:

python scripts/lunar_analysis.py 24.04.1983 07:00 Ижевск --lang ru --json --output result.json

For text output in terminal, set PYTHONIOENCODING=utf-8 and chcp 65001 (cmd) or use PowerShell with $env:PYTHONIOENCODING='utf-8'.

Disclaimer

This is an entertainment/educational tool, not a scientific method. Do not make medical or financial decisions based on astrological readings.

Changelog

v1.0.1 (2026-06-05)

• Encoding fix: Added --output file.json flag to lunar_analysis.py — writes JSON directly to file in UTF-8, bypassing Windows console cp1251 encoding issues
• draw_lunar.py now uses --output internally via temp file for subprocess communication
• Layout redesign: 2 wheels side-by-side (horizontal), vertically centered (cy=1440)
• Legend: 3 uniform-height groups (planets, aspects, elements) arranged horizontally below wheels
• Planet circles with 2-letter codes (SU, MO, ME...) matching astro-natal-chart style
• Colored aspect lines on natal wheel (red=square, blue=trine, green=sextile, etc.)
• Text panel widened to 2360px with smaller fonts for better text fit
• Output filename now includes person name: lunar_{name}_{date}_{lang}.png
• Target date shown in text panel instead of "today"
• Font/binary setup: All .ttf and .pyd files shipped as .dat (ClawHub-compatible), auto-copied at runtime
• Removed __pycache__ and generated .ttf/.pyd from skill directory
• Updated SKILL.md with encoding guide, new CLI args, and updated layout diagram

v1.0.0 (2026-06-05)

v1.2.0 (2026-06-07)

• Cosmetic: aspect symbols in text panel — Section 8 (Aspects) now renders graphical aspect symbols (△ □ ✶ ☌ ☍ ⚹ ⚺ ∠) from seguisym.ttf instead of text names (Trine, Square, etc.), matching the legend style
• Symbol color coding: aspect glyphs are rendered in their astrological colors (green △, red □, blue ✶, etc.) via _get_word_color + ASP_SYMBOL_COLORS map
• draw_lunar.py now supports --target-date flag — previously only lunar_analysis.py supported target dates via positional arg; now both scripts accept --target-date
• Subprocess propagation: draw_lunar.py passes --target-date through to lunar_analysis.py subprocess call
• lunar_analysis.py --target-date as explicit flag — previously only supported as 4th positional argument; now also parsed as --target-date flag for consistency
• Dual date format support: both DD.MM.YYYY and YYYY-MM-DD formats accepted for --target-date
• AI Conclusion rule added: SKILL.md now explicitly states that agents MUST always provide extended AI interpretation when possible; autonomous interpretation is a CLI fallback only
• Updated AI workflow: 4-step process (analyze → interpret → write conclusion → render chart) documented with explicit warning about missing conclusion = short output only

v1.1.0 (2026-06-06)

• Cosmetic overhaul of text panel: Font sizes now match astro-natal-chart (FS=19, FM=22, FL=26, LH=22)
• Text wrapping improved: Line width reduced to half (max_w = w // 2 - 20) for 2x faster line breaks
• Section headers raised: Title labels above both wheels moved up (80px from wheel edge) for better visual balance
• Colored planet names in text: Planet names in interpretation text are now rendered in their astrological colors (e.g., Марс in red, Венера in green, Уран in cyan)
• Colored aspect type names: Aspect type names (Square, Trine, Sextile, Quincunx, etc.) in text are colored to match the legend
• Section 9 (Conclusion) always visible: Now displays for both AI mode (overall text) and autonomous mode (summary.cycle_energy + summary.intensity)
• Fixed aspect list rendering: Transit Moon aspects in section 8 now show readable text instead of raw dict representation
• Fixed interp_text() robustness: Now handles all conclusion data formats — string, list, dict with description, dict with interpretation key, tuple
• Fixed nested function scope: Replaced nonlocal y pattern with mutable list _y = [y] to avoid UnboundLocalError in nested drawing functions
• Backup files preserved: draw_lunar.py.bak and draw_lunar.py.bak2 kept for rollback

v1.0.2 (2026-06-06)

• AI conclusion rendering restructured: AI interpretations are now distributed across
  metric sections (1–8) instead of being piled into section 9 (Conclusion)
• New AI conclusion JSON format: Metric keys at top level (moon_phase, lunar_day, etc.),
  each with interpretation field; overall field for section 9 summary only
• Helper functions interp_text() and show_interp() in draw_text_panel:
  unified extraction of interpretation text from dict, tuple, or string formats
• AI mode: full text displayed without truncation in sections 1–8; section 9 shows only overall
• Autonomous mode: preserved with text limits for compact layout
• Section 8 (Aspects): added AI interpretation of transit Moon aspects after the aspect list
• Conclusion JSON format documented in SKILL.md with examples for all supported formats
• Updated SKILL.md with AI Conclusion JSON Format specification

v1.0.1 (2026-06-05)

• Initial release
• Moon phase calculation (8 phases) with Swiss Ephemeris
• Exact phase date prediction (New Moon, First Quarter, Full Moon, Last Quarter)
• Transit Moon → Natal Moon aspects (personal lunar cycle)
• Personal solar-lunar phase (Moon → Natal Sun)
• Transit Moon through natal houses (Placidus)
• Lunar day (tithi) with 30-day Vedic meanings
• Moon speed analysis (fast/slow emotional processing)
• Illumination percentage and Earth distance
• Perigee/Apogee tracking
• Transit Moon aspects to all natal planets
• Bilingual text output (RU/EN)
• JSON export for AI integration
• 2-wheel side-by-side chart layout (5760×2880 px)
• Horizontal 3-group legend below wheels (planets, aspects, elements — uniform height)
• Text analysis panel with target date and person name
• Output filename includes person name and date: lunar_{name}_{date}_{lang}.png
• Bundled fonts and swisseph as .dat files (ClawHub-compatible, auto-copied at runtime)
• Vertical wheel centers at image middle (cy=1440), legend fits below