A personal Vedic astrology transit app. Enter your natal chart once; Aspectarian computes active transit contacts using Parāśaran dṛṣṭi and yuti (sign-based, no orbs) and generates an interpretation via Claude. Includes a 30-day calendar, Vimśottarī daśā display, transit duration indicators, and aṣṭakavarga-informed readings.
Prerequisites
- macOS (tested on macOS 12+, Intel and Apple Silicon)
- Python 3.12 or later — download from python.org
- Anthropic API key — get one at console.anthropic.com
- Xcode Command Line Tools — required to compile system libraries. The setup script checks for this automatically and opens the installer if needed. You can also install in advance by running
xcode-select --installin Terminal.
Installation
-
Unzip the archive and open Terminal inside the folder:
-
Run the setup script (creates a virtual environment and installs all dependencies):
This takes about a minute on first run. You will see "Setup complete" when it finishes.
Running
Then open http://localhost:7842 in your browser.
On first launch, you will be taken through the setup wizard:
- Name — your display name
- API key — your Anthropic API key (stored securely in macOS Keychain; never written to disk)
- Birth data — date, time (UTC), and place of birth
- Preferences — default reading window, language, theme
After setup, Aspectarian opens directly to your transit reading.
What's included
| Path | Contents |
|---|---|
engine/ |
Ephemeris computation, contacts, daśā, aṣṭakavarga, calendar |
context/ |
System prompt assembly, symbol map |
session/ |
LLM client, NDJSON streaming, reading storage |
reports/ |
Day / week / month report logic |
storage/ |
SQLite models and async queries |
ui/ |
FastAPI app + Vanilla JS frontend |
ephemeris/ephe/ |
Swiss Ephemeris data files (required) |
data/ |
GeoNames city database for birth place search |
symbol_map.json |
Jyotiṣa interpretation framework |
config.py |
All configuration (overridable via env vars) |
Configuration
All settings have sensible defaults. Override by setting environment variables before running:
| Variable | Default | Description |
|---|---|---|
CLAUDE_MODEL |
claude-sonnet-4-6 |
Anthropic model |
CLAUDE_MAX_TOKENS |
8192 |
Max output tokens per reading |
PORT |
7842 |
Local server port |
HOST |
127.0.0.1 |
Bind address (localhost only) |
DB_PATH |
aspectarian.db |
Path to user database |
HISTORY_MAX_READINGS |
5 |
Past readings included in LLM context |
Example — run on a different port:
Data and privacy
- All computation runs locally — ephemeris, contacts, daśā, aṣṭakavarga.
- Your birth data and reading history are stored in
aspectarian.db(SQLite, local only). - Your API key is stored in macOS Keychain via the system keyring.
- Transit readings are sent to the Anthropic API (Claude) for interpretation. No data is stored by Anthropic beyond standard API logging.
Stopping the server
Press Ctrl-C in the Terminal window running ./run.sh.