Build with an agent
Give your coding agent the Ascendant docs, a prompt that sets the rules, and a checklist for reviewing what it writes.
These docs are written to be read by a coding agent. An agent can do two separate things with Ascendant:
| The agent should | Use | Where |
|---|---|---|
| Write code that calculates charts, dashas, and transits | The docs and a prompt | This page |
| Answer astrology questions from a saved birth chart | The Ascendant skill | Skills and plugins |
Start with the prompt
Getting started has a prompt for any coding agent. Paste it, replace the last line with your task, and send it. It carries the docs location, runtime pattern, time-zone handling, and school rules.
Give the agent the docs
Pick the form that fits the job:
| Form | Address | Use it for |
|---|---|---|
| Index | /llms.txt | Every page with a one-line description. Start here. |
| Everything | /llms-full.txt | All pages in one file, about 200 KB. Send it when the agent has the room. |
| One page | /docs/<page>.md | A single page as Markdown, such as /docs/quickstart.md or /docs/guides/transits.md. Getting started is /docs/index.md. |
| Copy button | Copy Markdown on each page | One page pasted into a chat. |
| Open menu | Open on each page | A page sent to ChatGPT, Claude, Cursor, or Scira AI, or its source on GitHub. |
| Types | node_modules/astro-ascendant | Exact signatures from the shipped TypeScript declarations, once installed. |
The API reference is generated from the published package, so its names and types are exact. The guides explain how the pieces fit.
Reading order
Done means the agent can name the guide and API page its task uses.
- Read
/llms.txtto see what exists. - Read the Quickstart and Core concepts for the vocabulary and the runtime pattern.
- Read the one guide for the task, such as settings, dashas, or transits.
- Look up each name in its API reference page before using it.
Effect
Ascendant is built on Effect 4, and names changed between releases. Add Effect's own
guide for current code: LLMS.md.
The Quickstart lists more Effect resources.
Keep the rules in your project
Put the rules in the file your agent reads every session, such as AGENTS.md or
CLAUDE.md:
## Astrology (astro-ascendant)
- Docs index: https://astro-ascendant.vercel.app/llms.txt. Read the relevant page
before writing code, and take names from the API reference.
- Effect docs: https://raw.githubusercontent.com/Effect-TS/effect/refs/heads/main/LLMS.md
- Build one `ManagedRuntime` from `Runtime.MainLayer`, reuse it, and dispose it at shutdown.
- Keep all moments in UTC. Convert local time with its IANA zone and the birth date,
using `DateTime.makeZoned` with `disambiguation: "reject"`. Ask for missing birth data.
- Calculate Placements once with `Chart.generate` and reuse them.
- Default is KrishnamurtiVP291 + Placidus (KP). Use Lahiri + WholeSign for Parashari.
Judge each question in one school, and report the settings used.
- Handle typed errors with `Effect.catchTag`, and let defects propagate.
- Describe results as mechanics: positions and periods, never predictions or
medical, legal, or financial advice.Review what the agent wrote
Each row is a mistake this library invites. Done means every row holds.
| Check | Why it matters |
|---|---|
One ManagedRuntime, created once | A runtime per request starts with an empty position cache. See Ephemeris adapters and caching. |
| Local time converted with the zone for that date | Offsets change over time, and a daylight-saving gap or overlap can shift a birth by an hour. See From local time to a Located Moment. |
| One school per judgment, settings stated | KP and Parashari use different ayanamsas and house systems. See Choose a school and settings. |
| Every function and import exists | Agents invent names or reach for removed ones. Chart.generate replaces Chart.project, removed in 6.0. |
Dasha.at and Dasha.atRashi results checked for null | They return null outside the timeline. See Dashas. |
| Errors handled by tag | Chart.generate fails typed on bad input. See Errors and typed failures. |
| Arudha Pada described as the plain projection | The library skips the classical adjustment. See Jaimini calculations. |
| Results framed as positions and periods | A calculation is not a promise. |
A known-good result
Have the agent calculate this birth and compare. A match means its runtime, time conversion, and chart code are almost certainly right.
- Birth:
2000-01-01 17:30local time,Asia/Kolkata, latitude12.9716, longitude77.5946 - Settings: defaults, KrishnamurtiVP291 with Placidus
| Point | Expected |
|---|---|
| D1 Lagna | 69.68°, Gemini, Ardra pada 1 |
| D9 Lagna sign | Sagittarius |
| Moon | 199.55°, Swati pada 4, not retrograde |
| Saturn | 16.62°, Bharani pada 1, retrograde |
The Quickstart builds this program and shows its full output. The settings recorded on each result give the agent, and you, something to cite. See Provenance and verification.
Agents that answer questions
The Ascendant skill saves birth data once and answers from that record with cited evidence:
npx ascendant-skills installIt works with Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Copilot, and other skill-compatible agents. See Skills and plugins for per-tool steps.