Caelus
TypeScript · browser, edge, Node, and MCP

Validated astrology computation in TypeScript

Caelus is a clean-room, MIT-licensed TypeScript suite for validated astrology computation. It computes planetary positions, charts, events, hellenistic timing techniques, Vedic methods, and citable chart facts across browser, edge, Node, and MCP clients, without Swiss Ephemeris code, AGPL licensing, or ephemeris files.

Quickstart →

DocsStarter templateMCP tools (34)

0.41Nano-arcsec worst deviation3,218Golden checks in CI34MCP tools for AI clients~97 KBEngine, gzipped0Runtime dependenciesMITLicensed, no AGPL
sky now · 2026-06-21 22:37 UT · sun 0°33' Cancer · moon 0°54' Libra

You pass a date, UT time, latitude, and longitude; the engine returns a chart object for your app, API, or AI tool. The full capability list, with a comparison against the other engines, is on Features.

Compute a chart

Terminal
npm install caelus
chart.ts
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
♈♉♊♋♌♍♎♏♐♑♒♓123456789101112ACMCDCIC☉19°27'☽13°17'☿27°50'♀13°01'♂7°30'♃14°50'♄24°18'℞♅8°21'℞♆13°50'℞♇15°30'℞⚷15°34'☊8°07'℞
The same chart, drawn by caelus-wheel: 1990-06-10 14:30 UT, Tampa.

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.

The packages

caelus

Chart math: positions, houses, aspects. Zero dependencies, ~97 KB gzipped.

caelus-mcp

Thirty-four chart tools for AI agents: natal charts, transits, synastry, event search, electional, lots, time-lords, directions, and the Vedic layer (nakshatras, dashas, vargas, yogas).

caelus-birth

Local birth time and place to UT, with DST and historical timezone rules.

caelus-wheel

React SVG chart wheel. SSR-safe, ~3.4 KB gzipped.

How it is checked

Two-stage CI. A Python reference engine is calibrated against Swiss Ephemeris, then the TypeScript port is replayed against 3,218 golden checks. Worst recorded deviation: 0.41 nano-arcsecond, far below any astronomical relevance, so a porting bug fails the build. Tables and methodology: Validation. Bugs the suite caught: Build Notes.

Frequently asked questions

Is Caelus free to use in commercial projects?
Yes. All four packages are MIT licensed, with no Swiss Ephemeris dependency and no AGPL obligations, so you can ship it in closed-source and commercial apps.
How accurate is it?
Every body's deviation from a reference ephemeris is measured and published, then replayed against thousands of golden checks in CI. The full tables are on the Validation page.
Do I need Swiss Ephemeris or ephemeris files?
No. The planetary data is embedded in the package, so there are no files to download or deploy. See Data Tiers for what ships in the bundle.
What date range does it cover?
Several centuries around the present. A body outside its fitted range, such as Chiron before about 1850 or after 2150, is omitted from the chart and listed under its unavailable field rather than guessed. See Edge Cases.
Does it support Vedic astrology, or only Western?
Both. Alongside the Western chart it computes nakshatras, the Vimshottari, Yogini, and Ashtottari dashas, the divisional charts (vargas), and the yogas. See Vedic & Jyotish.
Can charts be computed without sending birth data to a server?
Yes. The engine does no I/O and runs in the browser, so an app can compute a chart entirely on the client and never transmit birth data. Try the Playground; details on Privacy.
Can I use it with AI assistants like Claude or Cursor?
Yes. caelus-mcp exposes thirty-four chart tools over the Model Context Protocol, available hosted or as a local stdio server. See MCP Setup.
Does it interpret a chart, or just compute it?
It computes; you interpret. The engine stops at validated geometry and ships no flavour text. For generated readings it provides an interpretation layer: a chart projects into ranked, citable fact atoms that a rule corpus or an LLM plugs into, with citation auditing to keep an AI grounded in the real chart. The meaning is always yours and always traceable to a fact.
Can it chart a forecast, a fictional character, or an archetype?
Yes. The provenance layer declares what the chart is (Realm) and how its time and place are known. realize() routes to the ephemeris or the geometric compiler, and passes certainty into the interpretation layer so a forecast reads as provisional and an inexact birth time down-weights the Moon and angles.

Start building

Quickstart →