Build a Free I Ching Divination App With AI Readings

Updated 5 November 2026 · Standard formula, shown below

Build a free web app that casts an I Ching hexagram, identifies changing lines and offers an AI-generated interpretation. You’ll need a place to host a small web app, a way to make AI requests securely, and a clear distinction between the traditional casting result and the model’s optional reading.

What You’ll Need

A computer and a code editor, plus a current web browser for testing.
A free hosting account that supports a front-end site and server-side functions. Check its current limits before relying on a free tier.
An AI provider account and API key if you want generated readings. Availability, usage limits and billing terms vary; do not assume API access is free just because the app is free to use.
A hexagram reference dataset: 64 entries with names, upper and lower trigrams, and reliable text you have permission to use. Verify translation and licensing before publishing.
Basic familiarity with HTML, CSS and JavaScript, or a starter template you can adapt.

Step-by-Step

Decide what “free” means. Write down whether the app must be free to build, free for visitors, or both. Hosting providers often offer limited free plans, while AI requests can incur costs. Set a usage cap, disable paid usage where available, or make AI readings optional and explain any limits. Never promise unlimited free readings unless you can guarantee that.
Choose your casting method. For a simple, transparent first version, use three-coin casting. Each of six lines is made by tossing three coins: heads count as 3 and tails as 2. Totals of 6 and 9 are changing lines; 7 and 8 are stable. Build lines from the bottom upward, as traditional hexagrams are conventionally recorded. Explain your method on screen; other casting methods can produce different probabilities.
Represent each line consistently. Store the six results in an array ordered bottom to top, with each value representing yin or yang and whether it changes. The primary hexagram uses the original lines. For the relating hexagram, flip only changing lines: yin becomes yang and yang becomes yin. Test this transformation with known cases before connecting any interpretation text.
Map the lines to the correct hexagram. Create a checked lookup table for all 64 line patterns. Do not assume that a decimal number or binary string matches a book’s numbering unless you have verified the ordering. Add automated tests for all 64 patterns, and include a few hand-checked examples from a source you trust. Display the hexagram number, name, and line diagram together so errors are easier to notice.
Build the basic interface first. Make a page with a question field, a “Cast” button, and a results area. Tell visitors that the I Ching is a reflective tradition, not a guaranteed prediction. After casting, show the six lines, which lines are changing, the primary hexagram and the relating hexagram when applicable. Keep the result visible even if the AI service is unavailable.
Add an optional AI reading. Send the model only the data it needs: the user’s question if provided, casting method, hexagram names and numbers, changing line positions, and relevant licensed source text or concise summaries. Ask for a grounded interpretation that separates source-based details from reflection, acknowledges uncertainty and avoids presenting outcomes as certain. Do not ask the model to invent quotations or claim that generated text is an authoritative translation.
Keep the API key on the server. Put the AI request in a server-side function or API route provided by your hosting setup. Store the secret in the host’s environment-variable settings, not in browser JavaScript, a public repository, or a page’s HTML. The browser calls your function; the function validates the request, calls the provider, and returns the reading. Add rate limits and input-length limits to reduce abuse and unexpected usage.
Handle privacy deliberately. Tell users whether questions are sent to an AI provider, whether readings are saved, and how they can clear local history. Avoid collecting names or other unnecessary personal information. If you save readings, explain retention and provide a way to delete them. Do not log full questions by default; logs can expose private reflections.
Test edge cases before launch. Try no changing lines, one changing line, several changing lines and all six changing lines. Confirm the changing-line positions and relating hexagram. Test empty or very long questions, network failures, provider errors, rate limits and malformed responses. The casting result should still appear when an AI reading fails.
Publish and monitor. Deploy the site and server function, then test the public URL on a phone and desktop. Check that secrets are absent from downloaded files and source maps. Review hosting and AI usage dashboards, set alerts or limits where offered, and add a clear contact or feedback route for reporting incorrect mappings.

Common Mistakes

Reversing the line order: Hexagrams are built from the bottom line upward. Drawing or storing top-first can silently return the wrong result.
Mixing casting conventions: A method’s line values and changing-line rules must be implemented as a set. Document the chosen method instead of combining rules from different methods.
Exposing the secret key: Any key included in front-end code can be copied by visitors. Use a server-side function and environment variables.
Using unverified text: Translations and commentaries may be copyrighted. Check permission, attribution requirements and the accuracy of your dataset.
Treating AI output as source text: A model can misstate meanings or fabricate quotations. Keep references separate and label generated interpretation clearly.

Tips

Show the casting method and line diagram so users can understand how the result was produced.
Offer a “cast without AI” option. This reduces cost and keeps the core divination feature useful during outages.
Use a version-controlled, machine-readable dataset and test its mappings automatically whenever it changes.
Keep the AI prompt focused. Ask for a short reading tied to the displayed hexagrams, with a practical reflection question rather than a confident prediction.
Make accessibility part of the first design: give each line a text label, use readable contrast, and ensure buttons work with a keyboard.

Troubleshooting

The hexagram looks upside down. Check whether your array starts with the bottom line, then verify how the diagram component displays its first item. Add a test that checks both the stored order and the rendered order.

The relating hexagram is wrong. Confirm that only 6 and 9 are marked as changing in the chosen three-coin method, and that each changing line flips once. Compare the output against a hand-worked example and inspect line positions individually.

The reading request fails. Check the server function’s logs for a missing environment variable, invalid request format, network problem, usage limit or provider error. Return a useful message to the visitor, preserve the cast result, and avoid displaying secrets or raw internal errors.

The key appears in browser tools. Remove it from front-end code, rotate or revoke the exposed key in the provider account, and move future requests to a server-side function. Removing a key from the latest commit alone does not make an exposed key safe.

Costs or traffic rise unexpectedly. Temporarily disable AI readings, reduce request limits, and review provider and hosting usage. Add per-user or per-IP throttling where appropriate, while being transparent that shared networks can affect multiple visitors.

Frequently Asked Questions

Can I build this without coding?
Possibly, using a no-code site builder with server-side integrations, but you still need to verify line ordering, protect API credentials and test all 64 mappings.

Can the app be completely free?
The basic casting feature can run without an AI service. Hosting and AI providers may impose limits or charges, so check current terms and set usage controls.

Does AI provide an authentic I Ching reading?
It generates an interpretation from its prompt and supplied information; it is not a traditional authority. Present it as optional reflection and show the underlying cast separately.

Should I store a visitor’s question?
Not unless saving it is necessary and clearly explained. If you add history, disclose where it is stored, how long it remains and how users can delete it.

What if I want another casting method?
Add it as a separately named option with its own documented rules and tests. Do not change the meaning of existing results without telling users.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.