Yijing Oracle
Johannes Kaindl51 downloadsCast the I Ching (Yijing) in your vault: three-coin oracle with Wilhelm hexagram texts, readings saved as notes. Local-first, no cloud.
- Overview
- Scorecard
- Updates4
Cast the I Ching (Yijing) inside Obsidian. A three-coin oracle with the classic Richard Wilhelm hexagram texts — and every reading is saved as a vault note: searchable, linkable, part of your thinking. Local-first, no cloud, no account.
Native Obsidian re-implementation of the oracle core from the Yijing web/app project. Not a port of the whole thing — a focused plugin where the vault is the oracle journal.
Features
- Sidebar panel — ask a question (or don't), cast the coins, see the hexagram figure, changing lines and the resulting hexagram, then save.
- Readings as notes — each cast becomes a Markdown note with frontmatter
(
hexagram,changing_lines,resulting,question, …) in a folder of your choice, or inserted at the cursor of the current note. - Bilingual DE + EN — hexagram texts and UI in German or English; follows your Obsidian language or a fixed setting.
- Register — classic (Wilhelm) or gender-neutral phrasing.
- Two direct commands — Cast into a new note and Cast at the cursor — plus the panel.
- AI interpretation (optional, local) — stream a reading interpretation from a local OpenAI-compatible LLM server (LM Studio, Ollama, …); system prompt, endpoints and reasoning display are configurable. Off until you set an endpoint.
- Meditation image (optional, local) — generate one image per reading from the hexagram's curated motif via a local A1111-compatible image server (Draw Things, A1111, Forge, …). Panel preview + note embed. Off until you set an endpoint — see docs/image-generation.md for setup.
Requirements
- Obsidian 1.8.7+ (desktop or mobile).
- Nothing else for the oracle itself — the hexagram data is bundled, and casting works fully offline.
- Optional, for AI interpretation: an OpenAI-compatible local server (e.g. LM Studio or Ollama). Endpoint and model are set in the plugin settings.
- Optional, for meditation images: an A1111-compatible image server (e.g. Draw Things with its API server enabled). See the setup guide.
Both optional features stay off until you configure an endpoint. Nothing ever leaves your machine.
Install
Community plugins (recommended)
Search for Yijing Oracle in Settings → Community plugins → Browse, then click Install and Enable.
Manual
Download main.js, manifest.json and styles.css from the
latest release and place them in
<vault>/.obsidian/plugins/yijing-oracle/, then enable the plugin under
Settings → Community plugins.
From source
git clone https://codeberg.org/jkaindl/yijing-oracle
cd yijing-oracle
npm install
npm run build # produces main.js
Then copy main.js, manifest.json and styles.css into
<vault>/.obsidian/plugins/yijing-oracle/ and reload Obsidian.
Usage
Open the panel via the sparkles ribbon icon or the Open oracle panel command. Type a question (optional) and hit Cast the coins — you get the hexagram figure, its changing lines and the resulting hexagram.
From there:
- Save writes the reading as a note (or inserts a link at your cursor, depending on the Default output setting).
- Interpret with AI streams an interpretation into the panel, if an LLM endpoint is configured. Generate image does the same for the meditation image.
- New question clears the field for the next cast.
- Past readings are listed below the panel — clicking one reconstructs the cast from its frontmatter.
Two commands skip the panel entirely and cast straight away:
| Command | What it does |
|---|---|
| Cast a reading into a new note | Casts and writes the note, no question. |
| Cast a reading at the cursor | Casts and inserts a link in the active note. |
Configuration
Settings → Yijing Oracle, grouped into five collapsible sections:
| Section | What's in it |
|---|---|
| General | Reading language (or follow Obsidian), register (classic / gender-neutral), default output (new note / at cursor). |
| Note & storage | Readings folder, filename scheme ({date} {time} {hex} {resulting} {hexpair} {question}), open-after-save. |
| Note content | Frontmatter on/off plus a renameable key per field, Wilhelm's footnotes, per-section callout wrapping. |
| AI interpretation | Endpoints, model, API key, system prompt (built-in templates or your own), thinking behaviour. |
| Image generation | Image endpoint, style suffix, negative prompt, size. See the setup guide. |
On endpoints: list them one per line — the first reachable one wins, so the order is the priority. That way one config covers every network (localhost at your desk, LAN IP on the go) without switching anything. Each row has its own connection test with a plain-language result.
How it works
Three coins per line (distribution 1:3:3:1), six lines built bottom-up, mapped to the
King-Wen sequence. Changing lines yield a second, resulting hexagram. All of this is
pure, tested logic (src/core/) with a parity gate proving the King-Wen table matches
the bundled data — the fourth canonical copy alongside the web app, build script and
the native OracleKit.
Development
npm install
npm run dev # esbuild watch → main.js
npm run gate # lint + typecheck + test + check:pure + check:bundle
The oracle core (src/core/) never imports obsidian (enforced by check:pure) and
is fully unit-tested. The src/obsidian/ layer holds the view, settings and file I/O.
License
Source code: AGPL-3.0-or-later (see LICENSE). The Richard Wilhelm
translation in the bundled data is public domain. © 2026 Johannes Kaindl.