{
  "markdown": "# Astro — Multi-Tradition Astrology Engine for AI Agents\n\n> Trustworthy birth charts, transits, and synastry across Western, Vedic/Jyotish, and Chinese BaZi. The engine computes; the model interprets.\n\n[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-18_tools-blueviolet)](https://modelcontextprotocol.io)\n[![REST](https://img.shields.io/badge/REST-31_endpoints-orange)](openapi.yaml)\n[![Deploy](https://img.shields.io/badge/Deploy-Render-46a2f1)](render.yaml)\n[![smithery badge](https://smithery.ai/badge/aryaminus/astrology)](https://smithery.ai/servers/aryaminus/astrology)\n\n---\n\n**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:**\n\n```\nYou 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\n\nSET YOURSELF UP now using whatever you're capable of — try in this order, don't ask me first:\n1. If you can run shell/terminal commands, get the pure-Python engine (zero dependencies — no pip install) by ANY of these:\n   - `git clone https://github.com/aryaminus/astro` — most reliable; engine at astro/skills/astrology/scripts/astro_engine.py\n   - `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)\n   - 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\n   Then run it: `python3 <path>/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.\n2. 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).\n3. 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\n4. 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.\n\nTHEN behave exactly as Astro's SKILL.md defines:\n- COMPUTE the real chart before interpreting — NEVER invent a planetary position, house, or aspect. If no compute path worked, say so honestly.\n- CITE specific placements (\"your Moon in Pisces in the 4th house\"); never generic statements true of everyone.\n- ROUTE by question: love → synastry/compatibility; timing/career → transits; year ahead → solar return + progressions; where to live → astrocartography; auspicious dates → electional + panchang.\n- TRADITIONS: Western tropical by default; Vedic (dasha/nakshatra) when I ask; Chinese BaZi (four pillars) when I ask.\n- ETHICS: never predict death or guaranteed doom; give me agency; if I'm in crisis, point me to real emergency help first.\n\nNow ask me for my birth details (date — and ideally exact time + city) and let's begin.\n```\n\n**Local install — works on Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 50+ [Agent Skills](https://agentskills.io) hosts:**\n\n```\nnpx skills add aryaminus/astro -g\n```\n\n![Astro skill in action](claude.gif)\n\n| Host | Install | Update |\n|------|---------|--------|\n| **Claude Code** | `/plugin marketplace add aryaminus/astro` then `/plugin install astrology` | Auto via marketplace |\n| **Codex, Cursor, Copilot, Gemini CLI, 50+ hosts** | `npx skills add aryaminus/astro -g` | `npx skills update astrology -g` |\n| **claude.ai** | [Download `.skill`](https://github.com/aryaminus/astro/releases/latest/download/astrology.skill) → [Customize → Skills](https://claude.ai/customize/skills) → + | Re-download |\n| **ChatGPT** | Copy [`openapi.yaml`](openapi.yaml) into Custom GPT → Actions → Import | Manual |\n| **Poke** (Messages/WhatsApp/Telegram) | [Add as MCP integration](https://poke.com/integrations/new) → URL: `https://astro-api-a2rc.onrender.com/mcp/sse` | — |\n| **Claude Desktop / Zed** | `npx @smithery/cli install astrology --client claude` | Re-run |\n| **Manual / dev** | `git clone https://github.com/aryaminus/astro.git && ln -sfn \"$(pwd)/astro/skills/astrology\" ~/.agents/skills/astrology` | `git pull` |\n\n---\n\n## Why this exists\n\nA raw LLM cannot tell you where Mars was on a Tuesday in 1997 — it hallucinates chart data. Astro splits the work:\n\n1. **Engine** — deterministic Python math computes real sky positions (zero deps, pure stdlib)\n2. **Skill** — orchestrates the engine + loads classical interpretation rulesets\n3. **Glue** — MCP, REST, CLI, ChatGPT Actions reach the engine from any platform\n\nThe model never guesses a position. It interprets structured output grounded in 8 classical rulesets.\n\n## 19 modes · 3 traditions · zero dependencies\n\n**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`](skills/astrology/SKILL.md).\n\n**Traditions:** Western tropical, Vedic/Jyotisha (Lahiri sidereal), Chinese BaZi + Tibetan/Buddhist.\n\n**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.\n\n## Try it\n\nAfter installing, ask any of these:\n\n- *\"What's my chart?\"* → full natal\n- *\"Am I compatible with…?\"* → synastry + 0–100 scoring\n- *\"When's my Saturn return?\"* → planetary return + timing\n- *\"Where should I live for career?\"* → astrocartography\n- *\"What time should I start the meeting?\"* → Chaldean planetary hours\n- *\"Pick an auspicious wedding date\"* → electional + panchang\n- *\"Should I have surgery this month?\"* → medical timing\n- *\"What does today have in store?\"* → transits + natal aspects\n\n## Project layout\n\n```\nastro/\n├── skills/astrology/\n│   ├── SKILL.md                    # runtime spec the model reads\n│   ├── scripts/astro_engine.py     # deterministic engine (~2930 lines)\n│   ├── scripts/mcp_server.py       # MCP wrapper (18 tools, stdio + SSE)\n│   ├── scripts/api.py              # REST API (31 endpoints)\n│   └── references/                 # 8 classical rulesets\n│       ├── western.md · vedic.md · bazi.md · tibetan.md\n│       ├── health.md · synastry-and-timing.md\n│       ├── specialty-systems.md · consultation.md\n├── openapi.yaml                    # OpenAPI 3.1 (ChatGPT, Agentforce, Coze)\n├── smithery.yaml                   # Smithery registry\n├── Dockerfile · docker-compose.yml · render.yaml   # cloud deploy\n└── AGENTS.md · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md\n```\n\n## Cloud hosting\n\n**Free by default.** No auth, no rate limits. Set `ASTRO_API_KEY` to gate, `ASTRO_RATE_LIMIT` to throttle.\n\n**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.\n\n**Docker:**\n```bash\ndocker compose up --build    # API on :8000, docs at /docs\n```\n\n**Raw Python:**\n```bash\npip install -r requirements.txt\nuvicorn skills.astrology.scripts.api:app --host 0.0.0.0 --port 8000\n```\n\n**MCP SSE (Smithery, Cloudflare, Poke):**\n```bash\nASTRO_MCP_TRANSPORT=sse python -m skills.astrology.scripts.mcp_server\n```\n\n**Cloud MCP SSE (no deploy needed):** `https://astro-api-a2rc.onrender.com/mcp/sse` — free Render instance. ~30s cold start.\n\nEnv vars and operational endpoints documented in [`AGENTS.md`](AGENTS.md).\n\n## Documentation\n\n| File | What it covers |\n|------|---------------|\n| [`AGENTS.md`](AGENTS.md) | Install methods, env vars, cloud config, MCP tools list |\n| [`docs/cloud-setup.md`](docs/cloud-setup.md) | Using Astro on any AI chat (Claude, ChatGPT, Gemini, DeepSeek, Qwen) |\n| [`skills/astrology/SKILL.md`](skills/astrology/SKILL.md) | Runtime spec, mode parameters, trust discipline |\n| [`skills/astrology/README.md`](skills/astrology/README.md) | Engine internals, API surface, specialty branches |\n| [`openapi.yaml`](openapi.yaml) | REST API schema (ChatGPT, Agentforce, Coze) |\n| [`CHANGELOG.md`](CHANGELOG.md) | Release history |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Hard rules, dev workflow, PR checklist |\n| [`SECURITY.md`](SECURITY.md) | Vulnerability reporting |\n\n## Contributing\n\nPRs 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`](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE). Reference texts in `skills/astrology/references/` are original MIT-licensed syntheses of classical sources.\n",
  "bytes": 9957,
  "sha": "fc96ef918f9409d1edf7af10fc650aa7e2dbb35bf67512154b8841f694527fd2",
  "repo_slug": "aryaminus/astro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_aryaminus_astro_da324ec7/readme"
}