English · 简体中文
A contemplative I Ching TUI for the terminal.
Set an intention. Cast a hexagram. Sit with what shows up.
- Cast with an optional intention. The casting ritual unfolds as an animation — three coins, six lines, then the hexagram rendered as a large braille glyph.
- Browse all 64 hexagrams with classical Chinese commentary (大象傳, 彖傳), English image and judgment, and Wilhelm-inspired notes.
- Journal every cast (with timestamp and intention) in append-only JSONL — your own divination history.
- Observe quiet patterns over that history (
pin the journal, oriching journal patterns) — a field of all 64 lit by what you've drawn, where movement falls, the yin/yang balance, the phase of day each was cast. Observation, never prediction. - Hook into LLMs the assistant can read your cast for further interpretation.
Raw ANSI, five hand-tuned themes (ink, bone, cinnabar, jade, river), four glyph-reveal animations, three Chinese fonts. No web technologies, no frameworks.
Runs under Node 18+ or Bun. Run without installing:
npx @pro-vi/iching # run with Node
bunx @pro-vi/iching # run with BunOr install globally:
npm install -g @pro-vi/iching # or: bun install -g @pro-vi/iching
iching # launch the TUI
iching cast "ship it?" # one-shot castOr clone and build:
git clone https://github.com/pro-vi/iching.git
cd iching
bun install
bun run build # builds dist/iching for your platformiching # interactive TUI
iching cast # one-shot cast (plain text)
iching cast "should I ship?" # with a question
iching cast --bound "ship it?" # bind the cast to the question and moment
iching cast --json # structured output
iching today # today's reading (cast in the TUI)
iching today --json # full reading payload for scripts/assistants
iching journal list # recent readings
iching journal list --hexagram 29 # readings where hexagram 29 appears
iching journal show today # today's reading
iching journal note "..." # attach a reflection note to the latest reading
iching journal patterns # quiet observation over every past reading
iching journal patterns --since 2026-01-01 --until 2026-03-31 # bound it to one season
iching journal patterns --json # the same derivation, structured for scripts
iching hexagram 1 # look up hexagram by number or name
iching dict water # open the dictionary on a search
iching dict # browse all 64 in TUI
iching config theme cinnabar # set themePress c to cast, t to return to today's reading, j for journal,
d for dictionary, s for settings, q to quit.
cast --json, today --json, and journal patterns --json emit stable,
self-describing payloads. In journal patterns --json, mind one contract
(the output states it in a basis field): descriptive counts tally every
reading; chance figures live in comparison blocks computed only over the
method-marked subset (coin/yarrow casts, whose line probabilities are known —
legacy entries have none). Never divide an all-readings count by an expected
from a comparison block; use that block's own count/expected, which share
a basis. (Every chance figure — including topTrigrams — lives in a
comparison block over the method-marked subset; uniform trigram geometry
still needs P(yang)=½, a property of the method, so it rests on the same basis
as the rest.) One further basis: timeOfDay rests on the timestamped
subset — its phase
counts sum to timeOfDay.timestamped, not total, since readings without a
recorded local hour are omitted rather than guessed.
Files follow the XDG Base Directory spec:
| File | Path | Purpose |
|---|---|---|
| Cache | ~/.cache/iching/daily-cache.json |
Most recent cast |
| Journal | ~/.local/state/iching/history.jsonl |
All casts |
| Notes | ~/.local/state/iching/notes.jsonl |
Reflection notes (sidecar to the journal) |
| Config | ~/.config/iching/config.json |
Theme, motion, glyph settings |
Override with ICHING_HOME env var or --data-dir flag.
Bun workspace monorepo. Four packages:
| Package | Responsibility |
|---|---|
@iching/core |
Pure domain — casting, derivation, hexagram data |
@iching/storage |
File persistence (JSON, JSONL, XDG paths) |
@iching/terminal |
TUI rendering — scenes, animation, themes (raw ANSI) |
@iching/cli |
Commander-based entry point, hook adapter |
bun test # run the test suite
bun run typecheck # tsc --noEmit
bun run build # compile the binary for your platform
bun run smoke # end-to-end smoke test of the built binaryVision notes and the current scope spec are mapped in docs/README.md.
The cast is true. If true, the hexagram is already everywhere in the day — the project, the conversation, the code, the decisions. It isn't a message to decode. It's a lens already present.
Observe. Don't interpret.
MIT