Responsive image

I-Ching: App of Changes

"Of all the versions I've used, your renderings of the texts are my heart-felt favorites. They have inspired me, made me laugh and cry and everything in between."

Full library of hexagrams for research, personal journal to store your readings, trigram information, helpful help, social media share & much more!

Download the app: For Android, iPhone & iPad, or Kindle.

Android app on Google Play
Responsive badge
amazon store button

Thousands of years of wisdom in your pocket, ready to assist you in reflecting on decisions large and small. Ask the I-Ching a question and you summon up ancient philosophy, timeless archetypes, and the magic poetry of synchronicity.

Available now in the Apple Store for iPad and iPhone, Kindle and for Android on Google Play. I-Ching: App of Changes Owl

The App

I Ching: The App of Changes brings a 3000-year-old work of philosophy and wisdom to an app that draws on western writing from 16th century poetry to Pynchon, from Dylan Thomas to the Dead.

The I-Ching was considered a fortune-telling text in ancient China, and a kind of psychic mirror by Carl Jung: you let the imagery, the archetypes, the language echo around in your head; your thoughts attach to them, your guesses at what they mean are glimpses into your own inclinations toward the question. What you're really trying to get at is an answer you already know, and which the book simply helps you unearth.

It's been used by artists as a creative aid, and by at least one writer to determine the plot of his book: legendary sci-fi author Philip K. Dick incorporated the I-Ching into the plot of "The Man in the High Castle," but he also cast hexagrams to decide narrative branches and shape his characters. (Trivia: the name of one of the characters, Baynes, is derived from the name of the English translator of the version he used: the Wilhelm-Baynes.)

The I-Ching attempts to describe the world of birth, death, maturity, eating, drinking, sex, art, war, play, marriage, career change, natural disaster, success, failure, the climbing of mountains, the fall of governments, the hiring of staff, the singing of music, all in terms of the interplay between the dichotomies of the strong and the yielding, the dark and the light, the masculine and the feminine. There's little here about "good" and "evil": the wages of failure are remorse and humiliation. The work is infused with admonishments to courage and an abiding faith in humanity's quest for the moral, the benefit of the people, the superior.

The oracle is actually a binary system made up of lines, broken or solid. 6 lines capable of two states, 64 Hexagrams: it's a perfect divination system for replication by a binary software process.

But the software engine here doesn't use the three-coin method popular in the west. It replicates the entire process of sorting 50 yarrow stalks again and again to derive each line: this maintains the statistical likelihood of a changing line precisely, which the coin method does not. I've released the sorting engine on GitHub as an open source code scrap if you're digitally inclined and want to peek at what's going on under the hood.


I-Ching: The App of Changes is designed for simplicity. The interface consists of an input bar where you can ask your question, a bottom bar menu with Help, Library, and Review options, and a single button.

The original I-Ching was a ritual, one in which the question before you was thought about throughout the process of sorting yarrow stalks. That process happens in microseconds thanks to the I-Ching's software. You may want to take a minute or two to think deeply about your question as you compose it to honour the whole ritual thing. (If you're wondering why the code doesn't just throw three coins, see the code section for why that shortcut isn't mathematically identical to the older yarrow-stalk method.)

Type your question in the input box and press "Ask."

I-Ching: App of Changes Ask

A Yin-Yang symbol appears, gently pulsing, on the screen. Consider your question and press it. In the blink of an eye, the software has sorted 49 stalks into two random piles, east and west, three times, and each time extracted stalks four at a time until four or fewer remain, placed them between the virtual fingers of a virtual left hand, and calculated the resulting number to determine if the line you've cast is "Strong" (solid) or "Yielding" (broken) and whether or not it's a "Changing" (light gray) line.

I-Ching: App of Changes yin yang

Press the button six times. Pause to think about your question each time. The Hexagram will be generated, as is customary, from the bottom up.

Upon generating the last line, you'll be presented with the name of the Hexagram, its English translation, and a translation of the oracle's "Judgement" text. I-Ching: App of Changes Judgement

Below the oracle text, separated by a small version of the Hexagram, are original interpretations that I crafted and cribbed over the course of several years in the 1980s, when I wrote the original software version of this app to run from a single 128K floppy on an MS DOS computer.

At the bottom of the Judgement text, the Yin-Yang button once again takes you to the next screen, the Image. The Image is the heart of the Hexagram, describing the pertaining condition. The Judgement clothes it in advice about whether a given action will bring good fortune or misfortune, remorse or humiliation.

If a hexagram has no changing lines, it's not moving toward a new situation, and the Judgement and Image texts wholly describe the situation. If changing lines have been cast, you need to pay attention to the text of the lines themselves, and the hexagram that results from those changes. I-Ching: App of Changes changing Changing lines are shown in light gray, and animate between their strong and yielding state briefly after being cast. The Changed or transformed hexagram which results from their transition is shown entirely in gray, and only the Judgement and Image texts are considered.

In general, the bottom three changing lines are considered to describe the present, the decision, and a changing line in the top trigram is considered to describe the outcome, the future.

Lines are displayed in the order in which they're cast, so a changing line at the beginning will be displayed first, a changing line at the top last. The Changing Line texts are particularly relevant to the decision at hand. Do they describe the future that will be, or that might be? You'll need to ask yourself that question.

After you've viewed the line texts, the Yin-Yang button will take you to the transformed Hexagram: the result of your decision. It's composed of the hexagram described by your changing lines reversed: so a strong changing line becomes yielding and vice-versa. Only the Judgement and Image texts of the changed hexagram are relevant.

You can now cycle through the texts with the Yin-Yang button to review them, or ask a new question of the oracle.

To save your question and the hexagram that you've cast, press the Journal menu item at the bottom of the screen.

I-Ching: App of Changes journal screen

I-Ching: App of Changes confirm
You can edit the question that you asked before you save. Your hexagram will be saved in the journal. By pressing the blue text and hexagram in the "Cast" column you can revisit the hexagram complete with changing lines. You can delete entries by pressing the garbage can icon. If you wish to edit your question again, you can visit the cast, press Journal, edit your question and press save.

If you would like to read the text of any hexagram, the "Library" option at the bottom of the screen will call up links to all 64 hexagrams.
I-Ching: App of Changes library
The Help button links here, to these help pages. The Heart button will take you to the app\'s page on Google Play or iTunes Store, so you can leave multiple stars and a glowing review. ;-)

Apple Watch Help

I-Ching: App of Changes Well on the WatchI-Ching: App of Changes handoff

You generate a hexagram on the Apple Watch the same way you do in the main app: push the Yin Yang button six times. Once your hexagram is generated, it's shared via handoff with the Safari browser on your phone and, if you're set up to do so, the Safari browser on any of your Apple devices within range. Open the handoff link as you normally would by swiping up from your lock screen or clicking on the icon to the left of your Mac's dock. Your particular reading, changing lines and all, will be there. Why in the Safari browser and not in the app? Well, I'm working on that one. At the moment, the Apple Watch can't interact with apps like I-Ching written in javascript without special plugins. None of those plugins were working when I released version 3.1, but they are now. I hope to have a new version shortly in which the app itself will display your hexagram.

I-Ching: App of Changes restart When you are ready to generate a new hexagram, force-press the Apple Watch face to get the "Start Over" screen.

If you would like to read more about the I-Ching, here are two great compendium sites and a few sources I really like:
The I-Ching on the Net
I-Ching Bookmarks
Thoughts of a Taoist Babe
Joan Larimore's hexagram illustrations
And for a handy step-by-step introduction to the yarrow stalk cast method, check out this great instructable.
You may also enjoy a piece I wrote on Medium, which Wired picked up: My Quest to Bring Hippie Mysticism to the Apple Watch.

The Code: Behind the screen

The I-Ching can be consulted a number of different ways. You're basically generating a random number from the set 6,7,8,9 to determine whether a line is broken or unbroken and changing or unchanging. But different methods yield different likelihoods, and the coin method, in which three coins are tossed, and the yarrow method, in which 50 yarrow stalks are ritually sorted, yield different results. Depending on how you approach the book and its history, this is either a highly significant or a totally silly distinction. But as a math and coding challenge go, I saw it as essential that my app use the older, more complex Yarrow method.

Here follows the manner in which the I-Ching was consulted by using the yarrow stalk method. The software abstraction of this process that I wrote in Jquery is available at GitHub. (If you would like a more pictorial step-by-step, check out HellaDelicious's instructable here.)

Take 50 stalks. Remove one, set it aside. Randomly separate the remaining 49 stalks into two piles, East and West. Take one stalk from the West heap and hold it between thumb and forefinger of your left hand. Take stalks in groups of four from the East pile, until four or fewer stalks remain. Keep this remainder, place it between the ring and middle finger of the left hand. Take stalks in groups of four from the West pile until four or fewer stalks remain. Keep this remainder, and place it between the middle and forefingers of the left hand.

Your left hand now holds a sum of stalks equal to 9 or 5, being made up of one of the following possibilities:

 1+1+3=5 1+2+2=5 1+3+1=5 1+4+4=9 

If the number of stalks is nine, a value of 2 is assigned to this counting. If it was five, the number three is assigned. The 9 or 5 stalks are put aside.

The rest of the stalks (40 or 44 by now) are again divided into two piles and counted off as above. The possible outcomes this time are:

 1+1+2=4 1+2+1=4 1+3+4=8 1+4+3=8 

This time, an 8 stalk remainder is assigned the number

2. A 4 stalk remainder receives a 3. The four or eight stalks are set aside, and the remaining 36, 40, 32, or 38 stalks are again divided in two and counted off. The possibilities are again:

 1+1+2=4 1+2+1=4 

 1+3+4=8 1+4+3=8 

And again a remainder of 8 is valued at 2, a remainder of 4 at 3.

From these three operations result the following possibilities:

 2+2+3=7 2+3+3=8 2+3+2=7 2+2+2=6 3+2+2=7 3+3+2=8 3+2+3=8 3+3+3=9 

It is these results which determine whether a line is solid or broken. A 7 meant a strong, solid line. An 8 meant a yielding, broken line. A 9 was considered a strong moving toward yielding line. A 6 was a yielding moving toward strong line.

By repeating the above process six times, a hexagram was built up from the bottom.

Like most westerners exposed to the I-Ching, I was taught the coin method of generating a line, which is far easier than the method above. By this method, three coins are tossed. Heads are worth 2, tails 3. The possibilities were thus:

 Head+Head+Head=6 Head+Head+Tail=7 Head+Tail+Tail=8 Tail+Tail+Tail=9 

This means, however, a slight difference in probabilities from the yarrow stalk method. The chance of any one coin being head or tail is ALWAYS 50/50. However, the chance of a "Tail" on the first "Toss" in the yarrow stalk method is almost 3 to 1. Recall, the possible results for the first division of 49 stalks was this:

 1+1+3=5 (Value 3) 1+2+2=5 (Value 3) 1+3+1=5 (Value 3) 1+4+4=9 (Value 2) 

Of four possible outcomes, three of them result in a 5, only one in a 9. This means, in effect, that when we look to the lines, those generated by a 2 in the first place are less likely to occur than those that start with a 3:

 Less likely: 2+2+3=7 (Strong) 2+3+3=8 (Yielding) 2+3+2=7 (Strong) 2+2+2=6 (Yielding Changing) 

 More likely: 3+2+2=7 (Strong) 3+3+2=8 (Yielding) 

 3+2+3=8 (Yielding) 3+3+3=9 (Strong Changing) 

It therefore makes sense that Yielding lines are slightly more likely to show up than Strong lines, and that a yielding changing line is the least likely all possible combinations to turn up. This is because unlike the regular yielding and strong lines, the changing lines are each generated by only one possible combination of stalks. The yielding, changing combination, because it begins with 2, is therefore heavily disfavored over the strong changing line.

Which is all just to say that the coin method does not hold the same built-in bias that the yarrow stalk method has. Surely note must have been made by the ancients that a 6 was a relatively rare occurrence indeed. Certainly, anyone in frequent consultation with the book by the yarrow stalk method would have noted the anomaly. I noticed the reticence of 6 after many many runs of the developing program and thought my coding was somehow flawed. But no! Perseverance furthers. No Blame.

The Back Story

I wrote the following about the original 1989 release of what was then called I-Ching.exe. The full documentation of that project is available here.

The I-Ching found me through a girl, Maggie Condron, whom I was dating in college. She had an absolutely gorgeous hard-cover copy of the book, three real Chinese coins, and made quite an elaborate ceremony of consulting it. The book had a special pillow set up like an altar. There were candles, incense. I was skeptical about the whole thing, and raised a few Spockish Eyebrows, but the whole production was bewitching, and there was undeniable magic, even if the magic was nothing more than the good old alchemy of words.

I had rummaged around bookstores for a couple months trying to find my own copy, to no avail.

One day, Maggie and I were selling a bunch of used books at Second Story books in Washington, DC. Someone had just brought in a box before me which was still on the counter, unsorted. Lying on top was a mint condition copy of the Wilhelm-Baynes translation. Maggie looked at me with a cynicism-challenging smirk. I looked at my shoebox full of rat-eared paperbacks, picked up the beautiful hardbound I-ching and said "Trade?" It was one of synchronicity's finest hours.

When I started messing around with computers in the mid 80s, the parallels between the I-ching and software kept jumping out at me. Both are binary systems, built of ones and zeros and yesses and nos. 64 hexagrams, 64k memory, 512 texts etc etc -- it seemed the I-ching and computers were made for each other.

I was living in Italy when I found myself with a pirate version of Turbo Pascal (purchased from the Porta Portese market for the cost of the floppy), a 64K Compaq luggable, and time on my hands. I wrote my first tentative little bit of code to randomly generate six numbers, so I could cast the I-ching on the computer and look up the results in my book.

Pretty soon I had a plan to create a full-blown program complete with my own interpretations, a journal for storing answers to questions, a lookup table for finding texts by hexagram, a user-definable colour scheme, a graphical menu system, and all the bells and whistles you could ever want from a piece of mid-80s software.

I'd usually start coding around 7pm and hack away until well past midnight. Sometimes I'd spend the evening writing interpretations, sometimes it would be writing or debugging code.

As I got deeper into the code engine, I discovered things such as the anomaly of the coin flip. At first, I started coding three variables to behave just like a toss of three coins, which is one method of generating a hexagram. But then I realised that statistically, this really wasn't even a close apporximation of the more ancient "Yarrow Stalk" method. The coin method biased slightly away from changing lines (all heads or all tails on the three coins). So I wrote a procedure that took variables separated into two random counts equalling the "East" and "West" piles of the 49 stalks, and sorted them back and forth in exactly the way an ancient chinese sage would have done.

The code

This little baby was a true 80s hepcat in usability terms. It used a clone of the VERY cutting edge Lotus 1-2-3 menu system which I had to constantly recode because I kept forgetting to count from 0 instead of 1. Learned a lot about arrays from that menu system.

My biggest constraint was it had to deliver on the media of the day, which meant I needed to cram more than 500 pages of text, plus far too many thousands of lines of code, onto a single 160k floppy disk. I brought it in at 155 zipped, a feat which still amazes me given some of the filesizes I was originally working with. The answer was my own compression engine. It became clear after I was about a quarter way through writing texts that I would never get all 512 pages down to size. Each of the hexagrams required the Judgment text, the Image text, and six pages of changing line text. Each page of text was around 125 words.

But I could store some of those words as abbreviations, and by storing such strings as "ing" and "ch" and "the" as single-byte tokens using the extended ASCII set, I could reduce thousands of instances of those strings from several letters to a single byte. I became a compression maniac, trying to find sources for whether the word "that" or "which" was more frequent in the language to know which I should encode into my precious but limited trove of 128 ASCII "Tokens." Then one day I realized that I was missing massive savings by looking at the English language and not looking at my source material. The I-Ching holds a litany of repeating phrases such as "It furthers one to cross the great water," and "Good fortune without blame." I could collapse those entire phrases into a single byte token. I ran the new code over the text and Whoompf! down came the filesize like a punctured balloon. I remember doing a little Eureka dance on the empty Via Marmarata as I walked home at 3am, my head still reeling with code.

The Program

I published the final version in 1989 via one of the shareware forums on Compuserve. In those days, that was pretty good distribution. I also sent copies high and wide to friends and threw a few into the market at Porta Portese. It never earned me more than a few hundred bucks, but I had lots of emails of appreciation and enjoyed seeing it get mentioned in various news groups and forums over the years. There were a couple requests and offers to help update it to a windows version, but I never got around to it. I still have most of the original source code, but one library got corrupted a couple decades ago, and the thing won't recompile anymore (which is why my address still reads as Italy in the closing panel.) Tauntingly, I have the full backup of the original work on a hard disk that came out of that old Compaq Sewing Machine it was written on, but in those days Compaq hard disks bore a proprietary BIOS wake-up routine, and the disk can't be accessed by slotting it into any other PC. So until I dig up a working Compaq Portable II on Ebay and can resurrect the disk, the oracle is locked against revisions.

That last bit prompted an email, out of the blue one day in 2013, from Gary McCaskill, a former PC technician who told me he'd installed my programme on hundreds of computers he'd set up and made attractive with his own menus of shareware. He had a specialty in data recovery, and could he be of help recovering the data? He'd hoped I'd put the I-Ching into an IOS format. I shipped the disk off to him and he put in Herculean effort, even buying an old Portable Compaq II. He rescued enough of the code to get me moving on the project. And when at one point I got stuck, unable to recover a swath of texts, he did a rather extraordinary thing. He reminded me that I'd built a backdoor into the programme -- one that I'd long forgotten, that would allow me to extract every text in the programme: "Print to Disk!" Boom! I had all the material I'd written, and while it wasn't quite as structured as it would have been in code format, a few BBedit macros and a few late nights, and I had a complete XML file of text that had taken months of typing and creative hours. So a huge thanks to Gary for prompting me to move ahead, and for using a rare set of skills in obscure 1980s hardware to help chisel this fossil out of solid rock and breathe new life into it.

Here's something Gary wrote me about participating in this project that made my heart brim:

Now for a bit of synchronicity.

I'm 65 now, and I was talking to a friend less than a week ago about how much knowledge is lost to the world everytime a person dies. Then think about a generation passing, and so much of the knowledge that was needed in their time just isn't needed. I watched my grandfather cast a babbit bearing with crumbled asbestos fibers and grease for a mold. Steam engine mechanics are gone forever. But that knowledge isn't required, and so it has to be dropped by each generation to make room for the knowledge of the times.

And then I thought of the knowledge that I have that was essential for my profession 30 years ago, it's always the stuff that was inside a wide, flat, gray computer case. How to install a socketed memory chip, how to orient a flat ribbon cable connector, the difference between the floppy cable and the HDD cable, and commands like "debug g=c800:5" to access to the low level format routine on a WD controller card.

Anyway, because of our little project, I get to utilize skills that I've gained over several decades-- And it feels good. Thanks for letting me participate. Gary


Brian Fitzgerald
brianfit58 [at]
@brianfit on Twitter
brianfit on GitHub

Download the app: For Android, iPhone & iPad, or Kindle.

Android app on Google Play
Responsive badge
amazon store button

Privacy Policy

Your data is yours. I don't trade, sell, swap, or even capture email addresses or personal information about you. I use the Facebook SDK to track ad performance in reaching new customers, but I don't use it to collect info on existing users. I use Google Analytics to track app usage anonymously. Those tools will all reveal things like where and when a user opens the app, the operating system and hardware they're using, the screen they are viewing, and other information about their app usage. But I don't invoke Facebook login or any other protocol which provides individually identifiable user demographic and personal contact or behaviour info.