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-engine.sh, run-interpreter.sh, and
                                  the user.properties template.
dist/                            Build output (gitignored) — see below.
interpreter/                     Separate module + binary (dist/interpreter-cli):
                                  scores how significant a day's transits are,
                                  reading deck-engine's --format json output
                                  (see CLAUDE.md).
docs/                            Architecture/dataflow diagrams, input/output format reference.
Makefile                         Single root Makefile, builds both engine/ and interpreter/.

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

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

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

Running

Daily use, via dist/run-engine.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-engine.sh              # text output, language from user.properties (default en)
dist/run-engine.sh html          # HTML report with card art, open in a browser
dist/run-engine.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|json] [--lang en|de]

Interpreter (interpreter/, built by the same root make): scores how significant a day's transits are, reading deck-engine's --format json output — the two binaries compose over that JSON, they're never linked together. dist/run-interpreter.sh is the daily-use equivalent of run-engine.sh (same OS clock + user.properties inputs), piping straight into interpreter-cli:

dist/deck-engine ... --format json | dist/interpreter-cli
# or, for daily use:
dist/run-interpreter.sh

License

The engine source code in this repository (engine/src/, engine/scripts/) and the root Makefile are 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.