Astro Lunar Insights

Calculates precise lunar phases, Moon transits, aspects to natal planets, lunar days, and personal solar-lunar phases with charts and text analysis.

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

Requirement	Details
OS	Windows (x64)
Python	3.14.x
Runtime	Microsoft Visual C++ Redistributable 2015–2022 (x64)
Pillow	12.x — pip install pillow
Swiss Ephemeris	Bundled as swisseph.cp314-win_amd64.pyd.dat

---

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:

Aspect	Timing	Meaning
Conjunction	Every ~28 days	Personal New Moon — emotional reset, new cycle begins
Square	~7 & 21 days	Crisis point — need for action, tension
Opposition	~14 days	Personal Full Moon — emotional climax, awareness
Trine	~7 & 21 days	Harmony — intuition flows, good for planning
Sextile	~4 & 24 days	Opportunity — gentle support
Quincunx	~11 & 17 days	Adjustment — something needs realignment
Semisquare	~3.5 & 10.5 days	Minor irritation
Sesquiquadrate	~10.5 & 17.5 days	Restlessness — break patterns
Semisextile	~2 & 16 days	Subtle influence

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):

Phase	Elongation	Meaning
Personal New Moon	0°	Beginning of personal cycle. Inward energy. Start new projects.
Personal Crescent	45°	Emerging. Energy builds. First steps.
Personal First Quarter	90°	Action point. Challenges arise. Push through.
Personal Gibbous	135°	Refinement. Fine-tune approach.
Personal Full Moon	180°	CLIMAX. Maximum awareness. Emotional revelation.
Personal Disseminating	225°	Sharing. Teach what you've learned.
Personal Last Quarter	270°	Crisis of consciousness. Let go.
Personal Balsamic	315°	Rest. Reflection. Prepare for next cycle.

4. Transit Moon Through Natal Houses

Shows which life area is emotionally activated:

House	Life Area
I	Personality, appearance, self
II	Money, values, resources
III	Communication, siblings, learning
IV	Home, family, roots
V	Creativity, children, romance
VI	Health, work, routine
VII	Partnership, marriage
VIII	Transformation, shared resources
IX	Philosophy, travel, higher education
X	Career, reputation, public life
XI	Friends, groups, hopes
XII	Subconscious, solitude, karma

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

Argument	Description
date	Birth date DD.MM.YYYY
time	Birth time HH:MM
city	Birth city
--target-date	Analysis date DD.MM.YYYY (default: today)
--lang	Language: ru or en (default: ru)
--name	Person's name for display
--json	Output JSON instead of text
--output	Write JSON directly to file (UTF-8, bypasses console encoding)
--conclusion	Path to JSON file with AI-generated conclusion

---

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/:

Font	Purpose	Extension
seguisym.ttf.dat	Zodiac symbols ♈♉♊... + planet symbols ☉☽☿...	.dat (ClawHub-compatible)
segoeuisl.ttf.dat	Cyrillic, latin, digits	.dat (ClawHub-compatible)

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

---

Scripts Reference

Script	Purpose	Dependencies
scripts/lunar_analysis.py	Sole calculation engine. All lunar metrics, text + JSON output.	swisseph, math, json
scripts/draw_lunar.py	Renderer. Calls lunar_analysis.py --json, draws 5760×2880 chart.	subprocess, json, math, Pillow
scripts/swisseph.cp314-win_amd64.pyd.dat	Swiss Ephemeris binary (2 MB) — JPL DE431 ephemerides	MSVC++ Redist
scripts/seguisym.ttf.dat	Zodiac + planet symbol font	—
scripts/segoeuisl.ttf.dat	Cyrillic/latin font	—

---

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:
        {
          "overall": "...comprehensive summary...",
          "metrics": {
            "moon_phase": "...",
            "transit_moon_to_natal_moon": "...",
            "personal_phase": "...",
            "transit_moon_house": "...",
            "moon_speed": "..."
          }
        }
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. Otherwise, the script generates built-in autonomous interpretations (no overall summary).

AI Workflow (for OpenClaw agents)

Step 1: python scripts/lunar_analysis.py <date> <time> <city> --json --target-date <date>
Step 2: AI analyzes JSON and provides interpretation
Step 3: python scripts/draw_lunar.py <date> <time> <city> --lang ru --name "Name"

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

---

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)

• 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