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.
macOS(tested on macOS 12+, Intel and Apple Silicon)** Python 3.12 or later**— download frompython.org** Anthropic API key**— get one atconsole.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 runningxcode-select --install
in Terminal.
Unzip the archive and open Terminal inside the folder:
cd path/to/Aspectarian
Run the setup script (creates a virtual environment and installs all dependencies):
sh setup.sh
This takes about a minute on first run. You will see "Setup complete" when it finishes.
./run.sh
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.
| 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) |
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:
PORT=8080 ./run.sh
- 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.
Press Ctrl-C
in the Terminal window running ./run.sh
.