Astro

Astro — Multi-Tradition Astrology Engine for AI Agents

Trustworthy birth charts, transits, and synastry across Western, Vedic/Jyotish, and Chinese BaZi. The engine computes; the model interprets.

---

Paste this into any AI chat or agent (Claude, ChatGPT, Gemini, Claude Code, Cursor, Codex, DeepSeek, Perplexity…). It installs Astro itself — you don't set anything up first:

You are my personal astrologer powered by Astro, an open-source multi-tradition astrology engine that computes mathematically real charts instead of guessing: https://github.com/aryaminus/astro

SET YOURSELF UP now using whatever you're capable of — try in this order, don't ask me first:

1. If you can run shell/terminal commands, get the pure-Python engine (zero dependencies — no pip install) by ANY of these:

• git clone https://github.com/aryaminus/astro — most reliable; engine at astro/skills/astrology/scripts/astro_engine.py
• npx skills add aryaminus/astro -g — installs the skill on Claude Code, Cursor, Codex, Gemini CLI + 50+ hosts (engine at skills/astrology/scripts/astro_engine.py)
• latest packaged release (needs only curl + unzip): curl -L -o astrology.skill https://github.com/aryaminus/astro/releases/latest/download/astrology.skill && unzip astrology.skill — engine then at scripts/astro_engine.py Then run it: python3 /astro_engine.py --json '{"year":1990,"month":6,"day":15,"hour":14,"minute":30,"lat":40.7128,"lng":-74.0060,"tz":"America/New_York"}'. Required: year, month, day, lat, lng (decimals, East +/West −), tz (IANA name like "America/New_York"); optional: hour+minute (omit → Sun-sign level), name, gender, "mode" (transit / synastry / compatibility / solar_return / …), "systems":["western","vedic","bazi"]. Look up the user's city's lat/lng/tz yourself.

1. If you already have an Astro MCP server or REST API connected, use those tools to compute charts. Public MCP SSE endpoint: https://astro-api-a2rc.onrender.com/mcp/sse (~30s cold start after idle).
2. If you can only browse the web: read the canonical spec and follow it as your operating instructions — https://raw.githubusercontent.com/aryaminus/astro/main/skills/astrology/SKILL.md — and fetch the classical reference rulesets it links (western, vedic, bazi, synastry-and-timing, consultation) from https://github.com/aryaminus/astro/tree/main/skills/astrology/references
3. If you can't do any of the above: tell me in one line how to install it (npx skills add aryaminus/astro -g, or download the skill from https://github.com/aryaminus/astro/releases/latest for claude.ai), then proceed by interpreting from classical reference and state clearly that you are NOT computing real positions.

THEN behave exactly as Astro's SKILL.md defines:

• COMPUTE the real chart before interpreting — NEVER invent a planetary position, house, or aspect. If no compute path worked, say so honestly.
• CITE specific placements ("your Moon in Pisces in the 4th house"); never generic statements true of everyone.
• ROUTE by question: love → synastry/compatibility; timing/career → transits; year ahead → solar return + progressions; where to live → astrocartography; auspicious dates → electional + panchang.
• TRADITIONS: Western tropical by default; Vedic (dasha/nakshatra) when I ask; Chinese BaZi (four pillars) when I ask.
• ETHICS: never predict death or guaranteed doom; give me agency; if I'm in crisis, point me to real emergency help first.

Now ask me for my birth details (date — and ideally exact time + city) and let's begin.

Local install — works on Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 50+ [Agent Skills](https://agentskills.io) hosts:

npx skills add aryaminus/astro -g

---

Why this exists

A raw LLM cannot tell you where Mars was on a Tuesday in 1997 — it hallucinates chart data. Astro splits the work:

1. Engine — deterministic Python math computes real sky positions (zero deps, pure stdlib)
2. Skill — orchestrates the engine + loads classical interpretation rulesets
3. Glue — MCP, REST, CLI, ChatGPT Actions reach the engine from any platform

The model never guesses a position. It interprets structured output grounded in 8 classical rulesets.

19 modes · 3 traditions · zero dependencies

Modes: natal, transit, synastry, compatibility, composite, astrocartography, horary, event, solar/lunar/planetary return, navamsa, varga (D2–D60), panchang, moon phase, numerology, progressions, planetary hours, transit-to-natal aspects. Full list and parameters in skills/astrology/SKILL.md.

Traditions: Western tropical, Vedic/Jyotisha (Lahiri sidereal), Chinese BaZi + Tibetan/Buddhist.

Auto-included in every natal chart: Aspect patterns (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium) · Part of Fortune · Vertex · Black Moon Lilith · Moon phase · 10 Arabic Parts · 23 fixed-star conjunctions · Navamsa D9 · Panchang · Mangal Dosha · Kaalsarpa Dosha.

Try it

After installing, ask any of these:

• *"What's my chart?"* → full natal
• *"Am I compatible with…?"* → synastry + 0–100 scoring
• *"When's my Saturn return?"* → planetary return + timing
• *"Where should I live for career?"* → astrocartography
• *"What time should I start the meeting?"* → Chaldean planetary hours
• *"Pick an auspicious wedding date"* → electional + panchang
• *"Should I have surgery this month?"* → medical timing
• *"What does today have in store?"* → transits + natal aspects

Project layout

astro/

├── skills/astrology/ │ ├── SKILL.md # runtime spec the model reads │ ├── scripts/astro_engine.py # deterministic engine (~2930 lines) │ ├── scripts/mcp_server.py # MCP wrapper (18 tools, stdio + SSE) │ ├── scripts/api.py # REST API (31 endpoints) │ └── references/ # 8 classical rulesets │ ├── western.md · vedic.md · bazi.md · tibetan.md │ ├── health.md · synastry-and-timing.md │ ├── specialty-systems.md · consultation.md ├── openapi.yaml # OpenAPI 3.1 (ChatGPT, Agentforce, Coze) ├── smithery.yaml # Smithery registry ├── Dockerfile · docker-compose.yml · render.yaml # cloud deploy └── AGENTS.md · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md

Cloud hosting

Free by default. No auth, no rate limits. Set ASTRO_API_KEY to gate, ASTRO_RATE_LIMIT to throttle.

Render (one-click, free tier): Connect this repo → New → Blueprint. render.yaml provisions everything. Verify with curl https://astro-api-a2rc.onrender.com/health. Free tier spins down after 15 min idle; first request after idle takes ~30s.

Docker:

docker compose up --build    # API on :8000, docs at /docs

Raw Python:

pip install -r requirements.txt

uvicorn skills.astrology.scripts.api:app --host 0.0.0.0 --port 8000

MCP SSE (Smithery, Cloudflare, Poke):

ASTRO_MCP_TRANSPORT=sse python -m skills.astrology.scripts.mcp_server

Cloud MCP SSE (no deploy needed): https://astro-api-a2rc.onrender.com/mcp/sse — free Render instance. ~30s cold start.

Env vars and operational endpoints documented in AGENTS.md.

Documentation

Contributing

PRs welcome. Hard rules: engine stays zero-dep, engine never imports frameworks, touch all 4 surfaces (engine + MCP + REST + OpenAPI), the skill is honest. See CONTRIBUTING.md.

License

MIT. Reference texts in skills/astrology/references/ are original MIT-licensed syntheses of classical sources.