Vedic Astrology Consultation

Vedic astrology consultations and reports that reason the way a careful, experienced astrologer does — answering the question actually asked, weighing the few chart factors that matter, keeping competing indications visible, timing them, and saying how strongly the chart supports each conclusion. Calculations come from a private Swiss Ephemeris engine that runs on your own computer.

Astrology's predictive validity is not scientifically established. The consultation describes what a tradition's documented methods indicate and how strongly its factors agree. It never claims certainty and refuses death, diagnosis, fertility, legal and investment verdicts.

Project status

• Released: 3.7.0 (2026-10-25). Changes after it are listed under Unreleased in the CHANGELOG and ship only with the next release.

• Maintained by one person; issues and pull requests are read, but there is no support schedule.

• Scope is deliberately narrow: Parashari, with optional Jaimini and Lal Kitab lenses kept separate. Other systems (KP, Western, numerology) are not part of this edition.

Related MCP server: Astro MCP Server

Install in Claude

Claude desktop app or claude.ai: Customize → Plugins → Add → Add marketplace, enter Krish9688/vedic-astrology-consultation, then install Astrology Consultation (Vedic) (from Anthropic's documentation; not yet verified by this project).

Claude Code:

claude plugin marketplace add Krish9688/vedic-astrology-consultation

claude plugin install astrology-consultation@vedic-astrology

Then, in a session: /astrology-consultation:setup (builds the local engine and downloads the ephemeris; needs Python 3.11+ or uv and internet once), then /reload-plugins. Ask:

• "Calculate my chart — born 14 March 1992, 09:40, UTC+0, London (51.5N, 0.12W)"

• "What changes in my career over the next few years?"

• "Will I be in a serious relationship in the next two years?"

• "Create my 12-month report"

(That birth is the project's synthetic test chart, not a real person.)

¹ Tested on macOS with the Claude Code CLI: install from GitHub, the engine steps behind setup/doctor, MCP connected, tool calls from a test client. A signed-in model turn calling the tools has not been recorded yet.

Updating, disabling, rolling back, uninstalling, where files live and troubleshooting: docs/MARKETPLACE.md.

Why it is different

• Calculation is separate from interpretation. Positions, dashas and transits come from the local engine; the reasoning never invents a position, date or transit.

• Synthesis, not single placements. Conclusions need several independent factors to agree and are graded Strong / Moderate / Weak / Contradictory / Unknown — separately for whether, when and in what form.

• Contradictions are kept. Books and schools disagree; the contradiction register records both sides and the answer says what each side would change.

• Birth-time honesty. The engine recomputes the chart across ±0.5…15 minutes and says how much error each factor tolerates; unstable factors are not leaned on.

• Systems are not blended. Jaimini has its own methods; it is argued separately and compared only at the end.

• Life first. The person asked about their life; chart facts are the evidence, not the subject.

Architecture

Birth data → local Swiss Ephemeris engine (astro) → validated chart facts
           → question framing → consultation reasoning (promise → activation → trigger → scenarios
             → contradictions → confidence) ⇄ optional source lookup in your own books
           → consultation (chat) or Structured Report Model → Jinja2 → HTML → WeasyPrint → PDF

One engine, three interfaces — MCP (stdio or Streamable HTTP), REST (/api/v1, OpenAPI) and the astro CLI — all calling the same functions, so a chart computed through Claude, ChatGPT, Cursor or a script is the same chart. The plugin runs that engine through MCP; nothing is forked per AI client. Details: docs/ARCHITECTURE.md.

Repository layout

Other AI clients and scripts (no Claude plugin)

git clone https://github.com/Krish9688/vedic-astrology-consultation && cd vedic-astrology-consultation
./install.sh          # private venv, `astro` command, settings (private mode), ephemeris, health check

Then point any MCP client at .venv/bin/astro mcp, or run astro serve for the REST API (http://127.0.0.1:8766/api/v1/docs). Configuration for Claude Desktop, ChatGPT desktop/Codex, Cursor and Open WebUI, and which of them were actually tested: docs/CLIENT-INTEGRATIONS.md.

Birth details go in a file, not on the command line:

echo '{"date": "1992-03-14", "time": "09:40", "tz": 0, "lat": 51.5, "lon": -0.12}' > s1.json
.venv/bin/astro chart s1.json --md          # positions, vargas, dashas, transits, Shadbala, Ashtakavarga, Jaimini
.venv/bin/astro sensitivity s1.json --md    # minutes of birth-time error each factor tolerates

More engine commands

.venv/bin/astro dasha s1.json --md                     # Vimshottari periods
.venv/bin/astro transits s1.json --on 2027-01-01 --md  # transits and sign changes from a date
.venv/bin/astro sky 2026-01-01 2026-12-31              # retrograde stations and sign changes, no birth data
.venv/bin/astro sensitivity s1.json --span 120         # look ±2 hours instead of ±15 minutes

Requirements and configuration

• Python 3.11 or newer (or uv); runtime dependencies pyswisseph and pydantic. Optional extras: mcp (MCP server), api (FastAPI + Uvicorn for REST), report (Jinja2 + WeasyPrint for PDF).

• Ephemeris: the Swiss Ephemeris files (downloaded by setup, pinned SHA-256) cover 1800–2399; outside that the engine falls back to the built-in Moshier ephemeris and says so. Dates are accepted from year 2 to 2999.

• Settings live in ~/.config/astrology-consultation/config.toml (owner-only permissions), written by astro setup: mode, skill_dir, knowledge_dir, books_dir, reports_dir, data_dir, allow_remote, api_token, source_url, share_library_remotely. Unknown keys are reported and ignored. ASTRO_CONFIG points to another file.

Privacy

• All calculation is local; no tool sends birth data anywhere (default private mode).

• The MCP and REST servers bind to 127.0.0.1. Remote use needs both allow_remote = true and an api_token. If you let other people use the service over a network and you changed the code, AGPL-3.0 §13 requires you to offer them your modified source; set source_url in the config, and the service advertises it through get_engine_info, /api/v1/version and the token-free /api/v1/source. Library lookup (excerpts of your own books) is not served to remote clients unless you set share_library_remotely = true.

• No access logs; birth details are not logged. Predictions are logged only with explicit consent.

• This repository contains no personal data: every chart in tests and examples is synthetic.

Details: docs/PRIVACY.md.

Books and copyright

No books, book text, index or knowledge graph are distributed here. Book search and the page-cited knowledge graph work with your own legally obtained copies (docs/ADD-A-BOOK.md); without them the consultation works and says that source lookup is unavailable. The Lal Kitab rules, code and remedies in this edition are the project owner's own wording of books that are still in copyright; their redistribution status is not legally cleared and the owner accepts that risk. The Lal Kitab knowledge base, the Varshaphal table and all book text are not distributed (the Varshaphal script says its table is not installed). Per-book status: docs/COPYRIGHT.md.

Testing

Every push runs: Gitleaks (full history), a privacy and copyright check, version consistency, Anthropic's plugin validator (claude plugin validate --strict) on the marketplace and plugin, Ruff, the test suite (Hypothesis property tests, reference charts incl. polar and boundary cases, MCP/REST/CLI security tests), a plugin-launcher bootstrap with an MCP smoke test, skill self-tests, a PDF report render and a package check.

The marketplace flow — add marketplace → install → setup → doctor → MCP connected → synthetic chart → consultation context → report — was tested from GitHub on a clean, sandboxed Claude Code profile on 2026-10-03 (macOS; the engine, launcher and MCP also run in Linux CI). Update, disable/enable, rollback and uninstall were tested with a local copy of the marketplace. What was and wasn't tested for each client: docs/CLIENT-INTEGRATIONS.md; method and results: docs/TESTING.md.

Limitations

• Grades describe agreement within the tradition, not probabilities.

• No time-zone database: give the UTC offset at birth, including daylight saving.

• Not yet implemented: Chara/Yogini/Narayana dashas, ishta/kashta phala, bhava bala.

• Native Windows is not supported: the plugin's engine launcher is a POSIX shell script. On Windows, run Claude Code inside WSL 2.

• claude.ai chat cannot reach the local engine; ChatGPT on the web would need a public tunnel (not recommended).

• Ascendant- and divisional-chart claims are only as good as the birth time; the engine reports the tolerance.

• First run needs Python 3.11+ or uv and internet once (engine environment and ephemeris download).

• Remote mode has no TLS of its own: put it behind an SSH tunnel or a TLS reverse proxy.

• Adding books (astro add-book) needs the full repository, not the plugin.

• The prediction log has only been exercised with synthetic records.

Version history

The skill has evolved since v1.1 (2026-09-06); v3.5.0 was the first version published here, followed by 3.6.0, 3.6.1, 3.6.2, 3.6.3 and 3.7.0 (current). Full history: docs/VERSION-HISTORY.md · CHANGELOG.md.

Contributing and security

CONTRIBUTING.md · SECURITY.md. Never put real birth details in an issue, test or pull request: tests use invented charts only, and the privacy check rejects unreviewed birth records.

License

AGPL-3.0-or-later (engine), Apache-2.0 (skill scripts and plugin files), CC-BY-4.0 (method text and documentation); book quotations are not relicensed. Full terms: LICENSE and LICENSES/.