Responsive image

The journey is the answer.

I-Ching: App of Changes:
A 5000-year-old book of wisdom, a mystic collaborator, and companion to your curiosity.

I-Ching: App of Changes

The App

The I-Ching means many things to many people: it was considered a fortune-telling text in ancient China, a kind of psychic mirror on the subconscious by Carl Jung, a mystic guide by Greenpeace founder Robert Hunter, the inspiration for binary math to Gottfried Wilhelm von Liebniz.

It's been used by artists like John Cage, Merce Cunningham, Bob Dylan, Jasper Johns, Marcel Duchamp, Robert Rauschenberg, Brian Eno, and David Bowie, as a creative aid, and by at least one writer to determine the plot of his book: legendary sci-fi author Philip K. Dick imagined a fictional world in which the I-Ching provides glimpses of alternate meta-realities outside the narrative, including the one in which he cast hexagrams to decide plot and character features in "The Man in the High Castle."

The I-Ching attempts to describe the world of every day events through the interplay of dichotomies: 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 supreme rewards are harmony and the pursuit of excellence. The work is infused with admonishments to courage and an abiding appreciation for integrity, empathy, enlightened leadership, governance that benefits the people, the superior expression of art.

The oracle is a binary system. In fact, it was the inspiration for the mathematics of 1s and 0s that runs every digital device today. Instead of 1s and 0s, though, the I Ching uses broken and solid lines. By a series of random operations, most often the sorting of stalks or the tossing of coins, a pattern of six broken and unbroken lines are generated, constituting one of 64 hexagrams, each describing a particular situation or condition and a set of texts for interpretation. In addition to being broken or unbroken, a line may be changing or unchanging - in transition from strong to yielding or vice versa. Changing lines not only introduce additional texts, by their transition they bring another hexagram formed of their opposites into play for interpretation.

In generating hexagrams, the software engine in I-Ching:App of Changes 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 and a single yinyang button for generating lines.

Icons on the bottom bar allow you to choose between a Coin Menu (if you prefer to cast with real coins or real stalks), the Journal where you can store and review your readings, a Library of all the hexagrams and their line texts, a Help button, and the Review 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 truly reflect before you turn to the book. (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 set aside one stalk, sorted 49 others 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

I-Ching: App of Changes JudgementPress 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.

Below the oracle text, separated by a small version of the Hexagram, are original interpretations or commentaries that I've crafted and cribbed and tweaked over the course of the three decades since the project began 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.

The two trigrams which make up the hexagram are listed on a single line in blue. There are 8 trigrams, each associated with a number of elements, familial relations, and natural features. For more information on the constituent trigrams, press these links for a window of the trigram's associations and attributes. Dismiss the window and return to your cast by pressing "OK." Trigram Modal

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 gently through a range of grey colors 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 line of a trigram is considered to describe the present, the middle 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, perhaps. It's composed of the hexagram described by your changing lines reversed: so a strong changing line becomes yielding and vice-versa. In the classic reading method of Zhu Xi, 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, ask a subsequent question that your reading might have prompted, or ask a new question of the oracle. (There is one hexagram that will give you a stern lecture about impertinence in asking the same question twice. It's amusing to be told off by a 5,000 year old book for not paying attention.)

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.

Backup and Restore: In version 4.0+, at the bottom of your journal entries page you'll find a "Backup or Restore" link which will allow you to send an email copy of your data to yourself for safekeeping. That data can then be appended to the journal of any other version of the app (allowing you to keep the same journal on your iPad and iPhone, for example), or you can follow a link in the email to generate a version of your journal as a webpage which you can then save locally to a desktop computer.

Backup data for your journal consists of a DataBeginMarker, and data end marker of the form "ZeroLight", and a comma-delimited set of fields: date, question, and a string with hexagram information. Good data looks like this:

DataBeginMarker;null;null;null;Sun Mar 06 2016,Should I stay or should I go?,84748484648;Sun Mar 06 2016,Who knows where the time goes?,64846484848;Sun Mar 06 2016,How many roads must a man walk down?,74847484847;Sun Mar 06 2016,What's the story morning glory?,84849484847;ZeroLight;
When appending or overwriting a journal, take care not to change anything between "DataBeginMarker" and the "ZeroLight" marker. The journal can be corrupted by an unexpected apostrophe, a comma out of place, a semicolon that wanders from home. Always paste directly from the backup email, and not from a word processor. The engine is pretty tolerant of stray characters before and after the data markers, but it won't tolerate any nonsense in between! All that said, if you want to edit a question in your data, it's entirely possible provided you stick to letters and numbers and avoid significant punctuation like commas, apostrophes, and semicolons. But take care: there's really no way to recover a corrupted journal: fiddle with the data at your own risk, and make sure you keep an original backup intact by backing up and mailing your data to yourself regularly.

Library: 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

Trigram Lookup: If you're looking at the image of hexagram but don't know its name or number, the easiest way to look it up is by looking at the top three and bottom three lines -- the trigrams. There are eight possible trigrams, and by scrolling through the possibilities you can easily find the hexagram you seek. For each combination, a picture of your hexagram, its number and name will appear below. Press that and you'll be taken to the standard reading (no changing lines) for that hexagram. You'll find the Trigram Lookup menu at the bottom of the Library screen.

Beginning with version 6.0, you can look up any reading with digital notation. If for example you'd like to see hexagram 11 with a changing line in the second and top places, you'd enter "11.26" in the question box: the hexagram number followed by a dot and the positions, 1 through 6, of any changing lines.

Coin Menu

Version 4.0 of the app introduced a new menu item, the Coin Menu. A number of users wrote to say they loved the interpretations in the app, but preferred the Old Skool methods of casting their own coins or sorting their own stalks, in real life. They asked for a way to track each line they cast, and to then be able to look up the reading, changing lines and all, with the app. The Coin Menu allows you to choose several means of selecting lines: through the numeric value of the yarrow stalk cast (always 6,7,8, or 9), the Heads or Tails options of three coins, HHH for all Heads, HTT for one head and two tails, etc, or the graphic representations of unbroken and broken lines. By selecting one of the options, you generate a line on screen. By pressing six selections, you'll build your hexagram. At the sixth line, the software engine looks up your result.
Social Media share and Share Sheet: If you want to share your reading on social media, there's a row of icons on the bottom of each reading and library entry that will publish a link and/or an image of your reading to Twitter, Facebook, or an email you can send to anyone you choose. In addition, the option at the far left opens your device "Share Sheet" which means you can publish your question, the hexagram number and name (in English and the original Chinese), and a link to the reading to any app that has social sharing enabled. So that includes setting a reminder, adding a text note, pushing it out via What's App, storing it to Evernote, or adding it to your reading list for later.

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. It will also provide an option to send suggestions for how I can improve the app for you -- don't hold back, I like to hear new ideas and do my best to keep improving this puppy. And, seriously, if you really do like the app, please take a moment to give it a review in the iTunes App Store or on Google Play! ;-)

Apple Watch Help

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

The Apple Watch app uses Handoff to pass your reading over to your phone. Setting up handoff can be a bit tricky. Here's what you do:

You can test whether your handoff is working by opening an email on your watch. You should see the email icon pop up in the lower left hand corner of the lockscreen on your phone.

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.

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
Hilary Barrett's I Ching With Clarity -- probably the best I-Ching blog on the web.
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 originally wrote this software as a piece of PC DOS shareware, distributed via floppy disk and CompuServe, in 1989. It became an app for iPhone, Android, iPad, and Apple Watch in 2015, after a couple loyal users asked me to bring it out of the stone age and one extremely loyal user helped me unlock it from its floppy-disk carbon-freeze. Here's the story of the software's beginning, from 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

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 users, but I don't invoke login or any other protocol which would allow me to 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 -- to the level of country and city --, the operating system and hardware they're using, the screen they are viewing, and other information about app usage that allows me to track crashes and better understand behaviour flows. I don't collect individually identifiable user demographic, personal contact, or behaviour info. To learn more about, and to help defend, online privacy, please visit and support the Electronic Frontier Foundation.