Validated astrology computation in TypeScript

Compute a chart

You pass a date, a UT time, a latitude, and a longitude, and the engine returns a chart object your app, API, or AI tool can read.

npm install caelus

import { Engine, fmtLon } from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

const chart = engine.chart(
  1990, 6, 10, 14, 30, 0,
  27.95, -82.46,
  "placidus",
);

fmtLon(chart.bodies.sun.lon);   // "19°27' Gemini"
chart.bodies.saturn.retrograde; // true

Full walkthrough in the Quickstart, or try it live in the Playground. For a complete app, the caelus-starter template is a Next.js project with a birth form, timezone handling, and a chart wheel, deployable to Vercel in one click.

What it computes

• Charts

  Sun through Pluto, Chiron, and the nodes; twelve house systems; tropical and seven sidereal zodiacs.

• Events

  Rise, set, and transit; stations; lunar phases; solar and lunar eclipses with local circumstances.

• Derived charts

  Returns, progressions, solar arc, composite, Davison, harmonics, dignities, and sect.

• Hellenistic time-lords

  Lots, profections, firdaria, zodiacal releasing, and primary directions.

• Vedic & Jyotish

  Nakshatras, the Vimshottari, Yogini, and Ashtottari dashas, divisional charts, and yogas.

• Interpretation layer

  Ranked, citable fact atoms, a pluggable rule corpus, and LLM briefs with citation auditing.

• Sky View

  The visible sky from a place and moment as a pixel-precise prompt for AI image generation.

• Chart provenance

  Declare what a chart is (forecast, mythic, archetypal) and route to the ephemeris or the compiler.

• MCP server

  caelus-mcp gives Claude, Cursor, and other MCP clients thirty-five chart tools.

• In-browser computation

  Charts compute entirely in the browser, so an app never has to send birth data to a server.

The full capability list, along with a comparison against the other engines, is on Features.

The packages

How it is checked

CI checks the engine in two stages. A Python reference engine is first calibrated against Swiss Ephemeris, and the TypeScript port is then replayed against 3,397 golden checks derived from it. The worst deviation recorded across that suite is 0.61 nano-arcsecond, which sits far below any astronomically relevant scale, so a porting bug fails the build instead of reaching a release. The tables and the methodology behind them are on Validation, and the bugs this suite has caught are written up in the Build Notes.