ml
Deck in a Dash
A Pebble smartwatch app that produces a daily personalized tarot (Celtic Cross) and astrology (natal chart + transits) reading.
This repository holds the core engine: 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, designed so
it links straight into Pebble watch code 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 and Sepharial PDFs, 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,
reads out the full Celtic Cross spread with
every card's meaning, and closes with guidance
(every day, tailored to how significant it is)
tying the top transit to the spread, reading
deck-engine's --format json output. Supports
--format text|html|json and --lang en|de for
its own output too (see CLAUDE.md).
watch/ The actual Pebble watchapp - links engine/src/
and interpreter/src/ in directly (see CLAUDE.md's
"Portability to the watch"), plus its own
persistence, reading recompute, UI, daily
notification, and config page. Built separately
from the rest of this repo (`make watchapp`,
below) - requires the Pebble SDK.
docs/ Architecture/dataflow diagrams, input/output format reference.
build-image/ Dockerfile for the reproducible build environment
(C toolchain + Pebble SDK) used by CI and by the
build-image.sh/run-image.sh/upload-image.sh scripts
at the repo root (see "Building" below).
Makefile Single root Makefile, builds both engine/ and
interpreter/, and packages a release (`make package`).
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
make package # -> dist/deck-in-a-dash-<version>-linux-<arch>.tar.gz, a
# self-contained release bundle (binaries, scripts, img/, i18n/,
# LICENSE, docs) - version from the current git tag, or
# VERSION=1.2.3 make package to override
Requires only a C99 compiler and make — no other dependencies.
Building the watch app itself (watch/, the actual Pebble app)
needs the separate Pebble SDK (pebble on PATH), so it's a separate
target, not part of make/make test/make package above:
make watchapp # -> dist/deck-in-a-dash-<version>.pbw, same version
# resolution as `make package`
CI runs make watchapp too — .gitea/workflows/build.yml builds
and tests everything inside a container built from build-image/,
which bundles the Pebble SDK alongside the C toolchain so the runner
itself doesn't need either installed. To build/test that image
yourself, copy registry.env.example to registry.env and fill in
your registry credentials, then:
./build-image.sh # build and locally tag the image
./run-image.sh # run `make test package watchapp` inside it, against
# this checkout, for a CI-equivalent local build
./upload-image.sh # push the image so CI can pull it
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, reads out the full Celtic
Cross spread with every card's meaning, and closes with guidance tying
the day's biggest transit to the Attitude/Outcome cards - reading
deck-engine's --format json output. Its own output supports the same
--format text|html|json and --lang en|de as deck-engine (note this
--lang is independent of whatever language deck-engine was run
with - --format json is always language-independent, see
docs/input-output-format.md). dist/run-interpreter.sh is the
daily-use equivalent of run-engine.sh (same OS clock + user.properties
inputs, including user.properties' lang=), piping straight into
interpreter-cli:
dist/deck-engine ... --format json | dist/interpreter-cli [--format text|html|json] [--lang en|de]
# or, for daily use:
dist/run-interpreter.sh # text output, language from user.properties
dist/run-interpreter.sh html de # HTML report with card art, override the language
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.
Transit narrative text in interpreter/src/narrative.c is condensed
from Sepharial's Transits and Planetary Periods (1920), also in the
public domain, except the Moon and Pluto entries, which are original
(see the file's own comment).
Guidance text in interpreter/src/guidance.c is original, written for
this project.
engine/i18n/de.lang's translations of the above two files' text
(narrative.*/guidance.* keys) are original German translations made
for this project, same status as its card/spread text.