Features
What the engine computes, in one place. The counts are exact. Positions are checked against Swiss Ephemeris and JPL Horizons (see Methods), and per-body accuracy is published on Validation, not asserted.
Chart and positions
caelus-wheel from the engine's bodies, houses, angles, and aspects: 1990-06-10 14:30 UT, Tampa.Bodies
Thirteen in the default chart: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, and the mean and true lunar node. On request: mean and true Lilith (lunar apogee), five asteroids (Ceres, Pallas, Juno, Vesta, Pholus), the Uranian/Hamburg points, and a 318-star fixed catalog.
Houses, angles, and zodiacs
Twelve house systems: Placidus, Koch, Porphyry, Equal, Whole-sign, Regiomontanus, Campanus, Alcabitius, Morinus, Meridian, Polich-Page, and Vehlow, with a whole-sign fallback above the polar circles. Angles: Ascendant, Midheaven, vertex, and east point. Zodiac: tropical and seven sidereal ayanamsas (Lahiri, Fagan/Bradley, Krishnamurti, Raman, Yukteshwar, Galactic Center, and Spica). See Houses & Zodiacs.
Aspects and frames
Major aspects (conjunction, sextile, square, trine, opposition) with configurable orbs. Apparent geocentric or topocentric positions, in ecliptic longitude and latitude or right ascension and declination, with light-time, annual aberration, IAU 1980 nutation, and Vondrák 2011 precession.
Events
Rise, set, and meridian transit; longitude crossings; lunar phases; stations; Gauquelin sectors; parans (co-angular bodies, two on the rising, setting, or meridian axis at once); and solar and lunar eclipses, with types, times, and geography: the sub-solar point of greatest eclipse, the path of totality (north and south limits and width), and local circumstances (magnitude, obscuration, and contact times) for any observer. Timing bounds are on Validation.
Techniques
Derived charts
Solar and lunar returns, secondary progressions, solar arc directions, composite and Davison charts, harmonics, antiscia and contra-antiscia, declination aspects and parallels, out-of-bounds, essential dignities (qualitative, and William Lilly's weighted five-fold score with the almuten of a degree), and sect. See Derived Charts.
Hellenistic time-lords
Deterministic arithmetic on the validated positions: the seven Hermetic lots (Fortune, Spirit, and the rest), sect-aware; annual and monthly profections with the lord of the year; the firdaria, the Persian seventy-five-year planetary periods; zodiacal releasing from a lot, with the four levels and the loosing of the bond; and primary directions to the four angles and between planets, by the Ptolemy or Naibod key. See Hellenistic Time-Lords.
Vedic and Jyotish
A full Jyotish layer on the sidereal chart: nakshatras with padas and their ruling planets; three dasha systems, Vimshottari (120-year), Yogini (36-year), and Ashtottari (108-year), each with sub-periods read from the Moon's nakshatra; the Parashari divisional charts (vargas) D1, D2, D3, D9, D10, D12, and D30; and the yogas (the five Pancha Mahapurusha, Gajakesari, Budha-Aditya, Chandra-Mangala, Kemadruma, plus a lordship and graha-drishti layer with raja and dhana yogas and yogakarakas). Each convention is validated against a named authority, not asserted. See Vedic & Jyotish.
Electional
Applying and separating aspects, solar phase (cazimi, combust, under the beams), planetary hours, the void-of-course Moon, and house placement with angularity. These read off the validated positions, pinned to the Python reference.
Computation and search
Query, turbo, and search
A declarative when() query language finds the intervals where celestial predicates hold. Predicates combine with allOf, anyOf, and notOf, and the solver locates the boundaries by bisection. For bulk scans, the turbo tier evaluates segmented Chebyshev longitude packs fit to the engine. For ranked time searches, rankMoments scores every instant in a range and returns the best, with a non-blocking variant for the browser. See Recipes.
Matching and synthesis
A chart reduces to a feature vector, each body's longitude as a weighted point on the unit circle, so two configurations compare by cosine similarity and searchConfigurations ranks a time range by how closely the sky resembles a target form. The geometric compiler runs the other way: give compileForm weighted constraints and it finds the longitudes that best satisfy them, reports the residual, and flags a form as impossible when even the best fit falls short. Both are pure and pinned to the Python reference. See Recipes.
Patterns and chart signature
detectPatterns enumerates the classical configurations as structured objects: T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by house. Reported patterns are maximal, so a grand cross hides the T-squares inside it and a kite its grand trine. chartSignature reduces a chart to plain counts: the element, modality, quadrant, and hemisphere distributions, the dominant element, modality, and sign, and the classical chart ruler. Both are pure geometry, interpretation-free, and exposed over MCP. See Common Tasks.
Interpretation layer
The engine stops at facts; this is the seam where meaning plugs in.interpretationContext projects a chart into ranked, citable fact atoms: natal geometry, dispositors and receptions, fixed-star conjunctions and lots, transits and time-lords at a target instant, synastry/composite links between two charts, finer essential dignities, and sidereal nakshatra/varga/yoga when applicable;enrichContextOptions and enrichSynastryOptionswire the diachronic layer; selectors and a pluggable rule corpus turn them into a structured reading; and chartBrief hands an LLM only the validated facts, each tagged with a stable id, with auditCitations to verify what it cited. Pair with the provenance layer so forecasts, fiction, and inexact times get realm framing and certainty damping. See Interpretation.
Chart provenance
A chart is not always a verified birth instant. Realm declares what it is (observed, forecast, mythic, archetypal, …); TemporalAnchor and SpatialAnchor declare how time and place are known;realize() routes to the ephemeris or the geometric compiler. Certainty flows into interpretation so Moon and angles are down-weighted when the time is approximate. See Provenance.
Output and delivery
Visualization
The chart as a flat wheel, as a tilted celestial sphere with planets at their true ecliptic latitude, or as an astrocartography world map of the planetary angle lines, plus a graphic ephemeris of any value over time. The 3D aspect angle accounts for latitude rather than longitude alone. Sky View frames the visible sky from a place and moment as a pixel-precise prompt for AI image generation, with body positions, magnitudes, Moon phase, twilight, the Milky Way, and ecliptic, sign, house, and constellation overlays. Every view renders to SSR-safe SVG with no runtime dependencies. See Visualizations.
Packages
Four npm packages: caelus (the engine, zero runtime dependencies), caelus-birth (timezone and local-time resolution), caelus-wheel (server-rendered SVG charts), and caelus-mcp (the MCP server). The Python reference ships on PyPI as caelus-engine.
Integration
The MCP server exposes thirty-four chart tools over stdio and Streamable HTTP at /api/mcp; a REST endpoint answers at /api/chart. The engine does no file or network I/O, ships an embedded data tier and a Node loader, and runs in the browser, on edge runtimes, and in Node. See MCP Setup and Data Tiers.
Range and license
Supported range 1800–2149, with the precise Moon and Chiron fits spanning 1850–2150. MIT licensed, with no AGPL and no ephemeris files on disk. Provenance for every coefficient is on Provenance.
How it compares
The set is developer-facing engines and libraries, with the facts taken from each project's own docs and license. Swiss Ephemeris and Astronomy Engine compute positions and astronomical events; the zodiac, chart, and technique layers on top are the application's job, and Astronomy Engine carries no astrology layer at all. A check marks the developer-friendly answer; a dash means the capability is not built in.
License and platform
| Caelus | Swiss Ephemeris | Kerykeion | Immanuel | Circular Natal JS | Astronomy Engine | |
|---|---|---|---|---|---|---|
| License¹ | MIT | AGPL / paid | AGPL | AGPL | Unlicense | MIT |
| Language | TypeScript | C | Python | Python | JavaScript | TS / multi |
| Runs in the browser | ✓ | – | – | – | ✓ | ✓ |
| Ships without ephemeris files² | ✓ | – | – | – | ✓ | ✓ |
| Independent of Swiss Ephemeris | ✓ | – | – | – | ✓ | ✓ |
| MCP server for AI clients³ | ✓ | – | – | – | – | – |
What it computes
| Caelus | Swiss Ephemeris | Kerykeion | Immanuel | Circular Natal JS | Astronomy Engine | |
|---|---|---|---|---|---|---|
| Positions & aspects | ✓ | ✓ | ✓ | ✓ | ✓ | positions only |
| House systems | 12 | many | several | several | 7 | – |
| Sidereal zodiacs | 7 ayanamsas | ✓ | ✓ | ✓ | ✓ | – |
| Eclipses, rise/set, stations | ✓ | ✓ | – | – | – | ✓ |
| Derived charts (returns, progressions) | ✓ | – | ✓ | ✓ | – | – |
| Hellenistic time-lords (lots, profections, releasing) | ✓ | – | – | – | – | – |
| Vedic / Jyotish (dashas, vargas, yogas) | ✓ | – | – | – | – | – |
| Pattern detection (T-square, grand trine, yod) | ✓ | – | – | – | – | – |
| Accuracy published & CI-pinned | ✓ | reference | via Swiss Eph | via Swiss Eph | – | ✓ |
- 1 Swiss Ephemeris is dual-licensed: AGPL-3.0, or a paid Professional License from Astrodienst.
- 2 Swiss Ephemeris uses
.se1data files for full precision (a built-in mode runs without them at lower precision); Kerykeion and Immanuel build on it. - 3
caelus-mcpexposes thirty-four tools over the Model Context Protocol. Kerykeion serializes charts to XML for LLM prompts but ships no MCP server.
Sources: Swiss Ephemeris, Kerykeion, Immanuel, circular-natal-horoscope-js, and Astronomy Engine.