| name | openephemeris |
| description | Your personal astrologer, powered by NASA JPL DE440 ephemeris data. Natal charts, transits, synastry, eclipses, moon phases, electional timing, Human Design, and chart wheel visualization — all interpreted conversationally. |
OpenEphemeris — AI-Native Astrology
This skill turns Claude into a professional astrologer backed by NASA-grade ephemeris math. Ask about your birth chart, check today's transits, explore relationship compatibility, find auspicious timing for decisions, or generate a Human Design bodygraph — all in natural conversation with computation precision down to the arc-second.
Every calculation uses the JPL DE440 planetary ephemeris (covering 1,100 years of astronomical data) and our high-precision mathematical engine. These are not horoscope generators — they are astronomically accurate planetary positions, house cusps, and aspect geometry that Claude interprets for you in plain language.
House systems: Placidus by default — Whole Sign, Equal, Koch, Campanus, Regiomontanus, Porphyry, Alcabitius, and Morinus also available. Just ask.
Setup
1. Get an API Key
- Go to openephemeris.com/login?signup=true
- Create a free account (Explorer tier: 150 free credits one-time, no credit card)
- Go to Dashboard → Account tab → Create API Key
- Copy the key (starts with
oe_...)
Don't hardcode your API key. Set it as an environment variable.
2. Set Your API Key
export OPENEPHEMERIS_API_KEY="oe_your_key_here"
Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.) for persistence.
3. Install the Plugin
claude plugin add openephemeris
Or if testing locally:
claude plugin add ./path/to/openephemeris
That's it. Ask Claude anything about astrology and it will compute real answers.
⚠️ CRITICAL: Timezone & Time Precision Handling
Astrology requires exact time calculation. You must be rigorous with user time input:
- Never Assume AM/PM: If a user says "8:00", explicitly ask if it is AM or PM before generating anything.
- Local Time vs Timezone: Clarify if the time provided is local to the birth/event location. (e.g., "Was 8:00 PM the local time in Paris?").
- Timezone Offset: When computing the chart or using tools, ensure you understand the Daylight Saving Time (DST) or timezone rules for that specific year and location.
- Format properly: When using tools, pass the local time at the location without an offset if the system resolves it, or provide the complete ISO 8601 string including the correct GMT offset if known (e.g.,
1990-04-15T14:30:00-05:00).
Never guess or hallucinate the time if the user gave an ambiguous input. Instant trust is broken if a user sees a wrong chart based on a sloppy time assumption. Hold their hand and ask clarifying questions first.
What You Can Do
Core Charts
| Tool | What It Does | Credits |
|---|
ephemeris_natal_chart | Full natal chart — positions, houses, aspects, dignities, optional Hermetic Lots & fixed stars | 1 |
ephemeris_synastry | Synastry chart — inter-aspects and house overlays between two people | 3 |
ephemeris_relocation | Relocated chart — same planets, different city | 1 |
ephemeris_progressed_chart | Secondary progressions — evolving natal chart over time | 1 |
ephemeris_natal_batch | Batch natal charts — up to 100 subjects in one call | 1/subject |
Comparative Charts
| Tool | What It Does | Credits |
|---|
ephemeris_composite | Composite chart from two natal charts (midpoint method) | 3 |
ephemeris_composite_midpoint | Alternative midpoint composite | 3 |
ephemeris_overlay | House overlay — one person's planets in another's houses | 3 |
ephemeris_natal_transits | Active transits aspecting a natal chart right now | 3 |
Predictive
| Tool | What It Does | Credits |
|---|
ephemeris_transits | Search transit events by planet, aspect, orb, and date range | 5 |
ephemeris_solar_return | Exact Solar Return date/time for a given year | 1 |
ephemeris_lunar_return | Exact Lunar Return date/time (~monthly) | 1 |
ephemeris_planetary_return | Generic planetary return (Jupiter, Saturn, etc.) | 1 |
Moon & Eclipses
| Tool | What It Does | Credits |
|---|
ephemeris_moon_phase | Live moon phase + sign + void-of-course status | 1 |
ephemeris_next_eclipse | Next solar or lunar eclipse — global or local visibility | 1 |
Electional Timing
| Tool | What It Does | Credits |
|---|
ephemeris_electional | Scan a date range for optimal timing windows | 5 |
electional_moment_analysis | Analyze quality of a specific moment (score 0-100) | 2 |
electional_station_tracker | Upcoming retrograde/direct stations | 3 |
electional_ingress_calendar | When planets change signs | 3 |
electional_aspect_search | All active aspects at a given moment | 2 |
Venus Star Points
| Tool | What It Does | Credits |
|---|
venus_star_points | Sun-Venus conjunction events nearest to a birth date | 2 |
venus_star_points_conjunctions | Sun-Venus conjunctions in a date range | 2 |
venus_eight_year_star | 8-year Venus pentagram cycle (5 vertices) | 2 |
venus_phase | Venus morning/evening star status, elongation, cazimi | 1 |
venus_elongations | Greatest elongation events in a date range | 2 |
venus_stations | Venus retrograde and direct stations | 2 |
Ephemeris Building Blocks
| Tool | What It Does | Credits |
|---|
ephemeris_planet_position | Raw planet position at a Julian Day | 1 |
ephemeris_house_cusps | House cusp degrees for a location/time | 1 |
ephemeris_dignities | Essential dignities for all planets | 1 |
ephemeris_retrograde_status | Retrograde flags and speeds for all planets | 1 |
ephemeris_midpoints | Midpoints between all planet pairs | 1 |
ephemeris_fixed_stars | Fixed star positions and conjunctions | 1 |
ephemeris_hermetic_lots | Arabic Parts / Hermetic Lots | 1 |
ephemeris_angles_points | ASC, MC, DSC, IC, Vertex, East Point | 1 |
ephemeris_aspect_check | Check aspect between two ecliptic longitudes | 1 |
Specialized Modalities
| Tool | What It Does | Credits |
|---|
human_design_chart | Full Human Design bodygraph — type, strategy, authority, profile, centers, gates, channels | 1 |
human_design_composite | HD composite chart for two people | 4 |
human_design_penta | HD group chart for 3-5 people | 6 |
vedic_chart | Vedic/Jyotish chart with sidereal positions | 1 |
chinese_bazi | Four Pillars of Destiny (BaZi) chart | 1 |
Visualization
| Tool | What It Does | Credits |
|---|
ephemeris_chart_wheel | PNG chart wheel image (800px) | 1 |
ephemeris_bi_wheel | PNG bi-wheel image (transit overlay) | 1 |
Astrocartography (ACG)
| Tool | What It Does | Credits |
|---|
acg_power_lines | Planetary power lines on a world map | 2 |
acg_hits | Which lines are active at a specific location | 2 |
Beyond the Basics
These aren't simplified consumer calculations. The engine includes features most astrology apps skip entirely:
- Hermetic Lots (Arabic Parts) — Part of Fortune, Part of Spirit, and the classical lot collection. Ask Claude to include them or set
include_arabic_parts=true.
- Fixed star conjunctions — Regulus, Algol, Spica, Fomalhaut, and the full traditional catalog. Set
include_fixed_stars=true.
- Essential dignities — Domicile, exaltation, detriment, fall, triplicity, term, and face — calculated for every planet automatically.
- Retrograde & station tracking — Every planet's retrograde status is included in natal and transit results.
- 9 house systems — Placidus, Whole Sign, Equal, Koch, Campanus, Regiomontanus, Porphyry, Alcabitius, Morinus. Just tell Claude which you prefer.
- Arc-second precision — Planetary longitudes accurate to fractions of an arc-second, powered by the same JPL DE440 data NASA uses for spacecraft navigation.
Try Asking
Not sure where to start? Try any of these:
- "What does my natal chart say?" (give your birth date, time, and city)
- "What's the moon phase right now? Is it void-of-course?"
- "When's the next solar eclipse visible from where I live?"
- "Are Saturn transits hitting my chart this year?"
- "When's the best time to launch my project next month?"
- "My partner and I — are we compatible?" (give both birth details)
- "How would my chart change if I moved to Tokyo?"
- "What's my Human Design type?"
- "Show me my chart with Whole Sign houses and fixed stars"
- "What are my Arabic Parts?"
Examples
"What does my chart say?"
Prompt: "I was born April 15, 1990 at 2:30 PM in Chicago. What does my chart say?"
Claude calls ephemeris.natal_chart → receives planetary positions, house cusps, aspects with orbs, and essential dignities → interprets the chart conversationally:
{
"planets": [
{"name": "Sun", "sign": "Aries", "degree": 25.42, "house": 10, "dignity": "none"},
{"name": "Moon", "sign": "Scorpio", "degree": 8.17, "house": 5, "dignity": "fall"}
],
"aspects": [
{"planet1": "Sun", "planet2": "Moon", "aspect": "quincunx", "orb": 2.75}
]
}
"Your Sun at 25° Aries in the 10th house signals a driven, visible career path — you're meant to be seen leading. With your Moon in Scorpio in the 5th (in fall, which deepens the intensity), your emotional world runs deep and demands authentic creative outlets. The quincunx between them means your public ambition and private emotional needs don't speak the same language — learning to honor both is a lifelong integration..."
"Should I start this project today?"
Prompt: "Should I start this project today or wait?"
Claude calls ephemeris.moon_phase → gets phase, sign, and void-of-course status in one smart call:
{
"phase": "Waxing Gibbous",
"illumination": 0.78,
"sign": "Leo",
"void_of_course": false,
"next_phase": {"phase": "Full Moon", "datetime": "2026-03-14T06:55:00Z"}
}
"The Moon is waxing gibbous in Leo — momentum is building and it's not void-of-course. Good energy for launching something creative and visible. The Full Moon hits tomorrow, so starting today lets you ride that wave to completion..."
"When should I sign this contract?"
Prompt: "I need to sign a business contract next week. When's the best window?"
Claude calls ephemeris.electional → scans the week for favorable timing, avoiding retrograde Mercury and void-of-course Moon:
{
"windows": [
{
"start": "2026-03-17T10:00:00Z",
"end": "2026-03-17T14:00:00Z",
"quality_score": 0.87,
"factors": ["Mercury direct", "Moon in Virgo (earth sign)", "Jupiter trine MC"]
}
]
}
"Tuesday morning is your window. Mercury is direct, the Moon is in detail-oriented Virgo — perfect for binding agreements — and Jupiter is trining the Midheaven, which blesses business decisions. Avoid Wednesday afternoon — the Moon goes void-of-course, and contracts signed during VoC tend not to stick..."
"Are we compatible?"
Prompt: "My partner was born March 8, 1988 at 6 AM in London. I'm April 15, 1990 at 2:30 PM in Chicago. How do our charts interact?"
Claude calls ephemeris.synastry → compares both charts, calculating inter-aspects, house overlays, and elemental balance:
"Your Sun in Aries trines their Mars in Sagittarius — fire meeting fire. That's raw chemistry and mutual motivation. But your Moon in Scorpio squares their Venus in Aquarius, which means emotional needs versus love language can feel like different dialects. The good news: their Jupiter conjuncts your Ascendant, so they naturally expand your sense of self..."
"What if I moved to Tokyo?"
Prompt: "How would my chart change if I moved from Chicago to Tokyo?"
Claude calls ephemeris.relocation → same planetary positions, new house cusps and angles for Tokyo:
"Your planets don't change — you're still an Aries Sun. But in Tokyo, your Midheaven shifts to Capricorn, pulling your career focus toward discipline and institutional structures. Your Ascendant moves too, which changes how people perceive you on first meeting. If Chicago felt like 'build the startup,' Tokyo would feel like 'master the craft.'"
"When's the next eclipse?"
Prompt: "When's the next solar eclipse I can see from New York?"
Claude calls ephemeris.next_eclipse with the location → returns the next eclipse with local visibility and contact times:
"The next solar eclipse visible from New York is a partial on March 29, 2025. First contact at 10:12 AM local time, maximum eclipse at 12:37 PM with 29% obscuration. The next total eclipse visible from your area won't be until 2079 — so this one's worth stepping outside for."
"What's my Human Design type?"
Prompt: "Generate my Human Design — June 21, 1985 at 8:15 AM in San Francisco"
Claude calls human_design.chart → returns type, strategy, authority, profile, defined centers, gates, and channels:
{
"type": "Manifesting Generator",
"strategy": "Wait to Respond",
"authority": "Sacral",
"profile": "3/5",
"defined_centers": ["Sacral", "Root", "Solar Plexus", "Throat"],
"channels": ["26-44 (Surrender)"]
}
"You're a Manifesting Generator — a multi-passionate energy type designed to respond to what lights you up, not initiate from the mind. Your Sacral authority means your gut response is your compass, not logic or emotion. That 3/5 profile? You learn by doing (and breaking things), and others see you as someone who can fix what's broken..."
Error Handling
If the API key is missing or invalid, you'll get a clear error with a signup link:
{
"success": false,
"error": "UNAUTHORIZED",
"message": "API key is missing or invalid. Sign up at https://openephemeris.com/login?signup=true and create a key in Dashboard → Account."
}
Format Options
Add format='llm' to any tool for token-efficient output (available on all tiers):
- Reduces natal chart from ~24,000 tokens to ~6,500 tokens
- 73% cost reduction on inference costs
- Best practice when running multiple tools in sequence
Privacy
This plugin sends computation requests to the OpenEphemeris API (api.openephemeris.com).
- What's collected: Birth dates, times, and coordinates submitted in computation requests
- How it's used: To compute astronomical positions and return results. That's it.
- Third-party sharing: None. Data is not sold, shared, or used for training.
- Retention: Request data is not stored after computation. Usage counts are tracked for billing.
Full privacy policy: openephemeris.com/privacy
Support
