Nightbird

Nightbird is a Go library and CLI tool for classical Western astrology calculations.

Astronomical computations are based on the vsop87-go library (https://github.com/ilbagatto/vsop87-go).

The project focuses on a clean, testable core for building and analyzing astrological charts, with a minimal CLI for exploration and debugging.

---

Features

Chart Core

• Planetary positions (10 bodies)
• Angles (Ascendant, Midheaven, etc.)
• House cusps (multiple systems)

Houses

• Placidus (default)
• Koch, Regiomontanus, Campanus, Topocentric
• Equal (Asc / MC / Sign)
• Morinus

Aspects

• Configurable aspect sets
• Applying / separating motion
• Selection strategies for aspect conflicts on the same pair of objects:
  • best by priority — prefers the aspect type with higher predefined priority
  • best by orb — prefers the aspect with the tighter orb

Balance (Summary)

• Distribution by elements (Fire, Earth, Air, Water)
• Distribution by qualities (Cardinal, Fixed, Mutable)
• Based on 10 planetary bodies

---

Installation

Build the CLI locally:

go build -o nb ./cmd/nb

Then run it from the project root or move the binary to a directory in your PATH.

---

CLI Usage

The nb command provides a simple interface for inspecting charts.

Positions

nb -view positions -when 2025-10-02T08:00:00Z -lat 42.6977 -lon 23.3219

Shows:

• longitude
• latitude
• daily motion
• house position

Houses

nb -view houses -hsystem Placidus -when ... -lat ... -lon ...

Outputs house cusps for the selected system.

Aspects

nb -view aspects -when ... -lat ... -lon ...

Shows detected aspects with:

• orb
• applying / separating motion

Balance

nb -view balance -when ... -lat ... -lon ...

Displays distribution of planets by:

• elements
• qualities

---

Testing

Run the full test suite:

go test ./...

Run tests for a specific package:

go test ./pkg/chart/...

---

Architecture

Nightbird is organized into small, focused packages:

• chart — high-level orchestration (positions, houses, aspects, balance)
• houses — house system calculations
• aspects — aspect detection and selection
• types — core astrological categories (objects, elements, qualities)
• skyctx — astronomical context

The design principle is:

chart = orchestration, packages = pure calculations

---

Status

First iteration complete:

• positions
• houses
• aspects
• basic balance (elements & qualities)

Next steps:

• GUI layer
• predictive techniques
• synastry

---

License

MIT