Deck in a Dash

A Pebble smartwatch app that produces a daily personalized tarot (Celtic Cross) and astrology (natal chart + transits) reading.

Status: only the core engine exists so far — a plain-C, dependency-free library and standalone CLI (dist/deck-engine) that computes a full reading without needing a Pebble device, emulator, or SDK. The watchapp itself hasn't been built yet; the engine is designed so it can be linked into it later without rework.

What it computes

• Astrology: a personalized natal chart (Sun through Pluto, plus the Ascendant and whole-sign houses) from a birth date, time, and location, and the day's transits — including moon phase and aspects — against that chart.
• Tarot: a 10-card Celtic Cross spread, drawn from the 22 Major Arcana, with upright/reversed orientation per card. The full spread is deterministic: the same seed string always produces the same cards, in the same positions, with the same orientations. Card meanings and spread positions are sourced from A. E. Waite's The Pictorial Key to the Tarot (1911, public domain), in his own original drawing order.

Readings are available in English and German (--lang en/--lang de, or lang= in user.properties); adding another language is just dropping a translated key=value file into engine/i18n/ — see docs/input-output-format.md.

Repository layout

res/                             Tarot card art (22 RWS Major Arcana), the
                                  Waite PDF, logo, research notes.
engine/
  third_party/astronomy/         Vendored cosinekitty/astronomy C library (MIT).
  src/                           Engine source (rng, tarot, astro, i18n, reading, CLI).
  i18n/                          Translation files (en.lang, de.lang, ...).
  tests/smoke_test.c             Determinism, ephemeris, and i18n regression checks.
  scripts/                       run.sh and the user.properties template.
  Makefile
dist/                            Build output (gitignored) — see below.
docs/                            Architecture/dataflow diagrams, input/output format reference.

See CLAUDE.md for the detailed architecture and the sharp edges worth knowing before changing the engine, or the docs/ directory for diagrams (docs/architecture.md) and the full CLI/file/ struct format reference (docs/input-output-format.md).

Building

cd engine
make          # -> dist/deck-engine, dist/img/, dist/i18n/, dist/run.sh, dist/user.properties
make test     # builds and runs engine/tests/smoke_test.c

Requires only a C99 compiler and make — no other dependencies.

Running

Daily use, via dist/run.sh: pulls today's date and the current UTC time from the OS clock (used as the tarot seed and the transit moment) and reads your birth data from dist/user.properties. Edit that file first — it's seeded once from a placeholder template and is never overwritten by later builds:

dist/run.sh              # text output, language from user.properties (default en)
dist/run.sh html          # HTML report with card art, open in a browser
dist/run.sh html de       # override the language for this run

Direct CLI, with every input explicit:

dist/deck-engine --seed "2026-07-03" \
  --birth-date 1990-05-14 --birth-time 14:32 --birth-utc-offset 2 \
  --birth-lat 52.5200 --birth-lon 13.4050 \
  [--date YYYY-MM-DDTHH:MM] [--format text|html] [--lang en|de]

License

The engine source code in this repository (engine/src/, engine/scripts/, engine/Makefile) is released under the MIT License — see LICENSE.

engine/third_party/astronomy/ is vendored from cosinekitty/astronomy (MIT, unmodified) — see its VENDORED.md for the pinned commit.

Card and spread text in engine/src/tarot_data.c is condensed from A. E. Waite's The Pictorial Key to the Tarot (1911), which is in the public domain.