# Aspectarian – a Jyotiṣa transit reader for macOS using Claude

> Source: <https://github.com/SpecStudio-net/Aspectarian>
> Published: 2026-06-16 02:00:24+00:00

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 from[python.org](https://www.python.org/downloads/)** Anthropic API key**— get one at[console.anthropic.com](https://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 --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`

.