Caelus

The ephemeris is now just code.

• 🪐 Full natal charts: 13 bodies, twelve house systems, aspects, in ~85 KB
• 🆓 Free and MIT, commercial use included
• ⚖️ No AGPL, no 700 CHF license
• 📦 No ephemeris files: the data ships inside the bundle

The Packages

Four packages, all MIT, all on npm. Per-body accuracy against Swiss Ephemeris: Validation · Sources.

Get Started: Compute a Chart

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
chart.angles, chart.cusps, chart.aspects;

The same code runs in the browser, on edge runtimes, and in Node. Times are UT; for local birth times use caelus-birth below. Full API: the package README.

Get Started: Ask Your AI About the Sky

No code required. caelus-mcp gives Claude, Cursor, or any MCP client seven chart tools. Add this to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "caelus": { "command": "npx", "args": ["caelus-mcp"] }
  }
}

Then ask in plain language:

• “What's my natal chart? Born June 10 1990, 2:30pm, Tampa FL.”
• “When is Saturn square my natal Moon in the next two years?”
• “Compare my chart with my partner's.”

Tools: natal_chart, current_sky, transits, synastry, find_aspect_dates, rectification_grid, sky_events. Positions are computed by the engine, never recalled from training data, and every answer is deterministic.

Get Started: Real Birth Times and a Wheel

caelus-birth converts a local birth time and place to UT with historical timezone rules. A four-hour timezone mistake moves the Ascendant about 60°; this package exists so that never happens silently. caelus-wheel renders the chart as an SVG wheel (live demo).

import { toUT } from "caelus-birth";
import { ChartWheel } from "caelus-wheel";

const t = toUT({ year: 1990, month: 6, day: 10, hour: 14, minute: 30,
                 lat: 27.95, lon: -82.46 });   // resolves America/New_York, EDT
const chart = engine.chart(/* t.utc fields */);

<ChartWheel chart={chart} size={520} showAspects />

What This Is

Caelus computes apparent geocentric positions for the Sun, Moon, eight planets, Pluto, Chiron, and both lunar nodes, with speeds, retrograde flags, ASC/MC, twelve house systems, and major aspects. Optional bodies (Lilith, asteroids, Uranians) load from data packs. Valid 1800–2149. The coefficient data ships inside the bundle: VSOP87D planets, an abridged ELP-2000/82 Moon, Meeus's Pluto series, and Chebyshev fits of JPL data for Chiron and the precise-Moon tier.

The engine takes injected data and does no I/O, so one codebase serves three runtimes: this page (charts compute client-side in ~2 ms), the demo endpoint GET /api/chart, and Node, where caelus-mcp exposes seven chart tools to AI agents over MCP.

Why It Exists

Most astrology software computes positions with Swiss Ephemeris, and it earned that position: JPL DE431 compressed to 0.001″. It is also a 1997 C library with process-global state, it reads 2–97 MB of ephemeris files from a filesystem, and since v2.10.1 (June 2021) it is AGPL-3.0, dual-licensed at 700 CHF for closed source. None of that maps onto browsers or edge runtimes.

The MIT-licensed alternatives are astronomy libraries, not astrology engines: astronomy-engine stops at ±1 arcminute and computes no houses, nodes, or Chiron; astronomia has sub-arcsecond planets and no astrology layer. Caelus is written from the published record and covers the chart core at chart precision. Engine-by-engine comparison: Sources.

How It Is Checked

Two stages, both in CI. The Python reference is compared to Swiss Ephemeris 2.10 at hundreds of random instants across 1900–2099: planets ≤1″, precise-tier Moon ≤2.5″, angles and Placidus cusps ≤3.2″. The TypeScript engine must match the reference across 3,218 golden fixtures; worst recorded deviation 1.64 nano-arcseconds. Per-body deltas: Validation. Bugs the suite caught: Build Notes.

npm install caelusGitHubREST APIMCP Server