{
  "markdown": "# I Ching Divination\n\nAn MCP server for I Ching divination (Wilhelm-Baynes translation), compatible with [Goose](https://block.github.io/goose/), [Claude Code](https://github.com/anthropics/claude-code), and other MCP clients, plus a command-line utility.\n\n## Screenshots  \n## Claude Sonnet 4\n![claude-4-sonnet](./images/claude-4-sonnet.png)\n\n## Claude Sonnet 3.5 \n![claude-3-5-sonnet](./images/claude-3-5-sonnet.png)\n\n## GPT 4.1\n![gpt-4-1](./images/gpt-4-1.png)\n\n## Features\n\n- **Three coins method** divination following traditional practices\n- **Wilhelm-Baynes translation** with complete hexagram meanings, judgments, and line interpretations\n- **Multiple interfaces**: CLI tool, MCP server for Goose, Claude Code, and other MCP-compatible clients\n- **Flexible input formats**: hexagram numbers, Unicode characters, line numbers, or changing hexagram notation\n- **Rich output formats**: brief, full interpretations, JSON, and MOTD formats\n- **Changing line support** with transformation interpretations\n\n## Quick Start\n\nThis tool provides three interfaces:\n\n- **[CLI Tool](#cli-usage)** - Command-line divination and interpretation\n- **[Goose Extension](#goose-extension-setup)** - MCP server for Goose AI assistant\n- **[Claude Code Plugin](#claude-code-setup)** - Native plugin for Claude Code\n\nAll interfaces use the same binaries. Start with [Installation](#installation) below, then jump to your preferred interface.\n\n## Installation\n\nThis section covers installing the binaries needed for **all** interfaces (CLI, Goose, and Claude Code).\n\n### Prerequisites\n\n- Rust 1.85.1 or later (for 2024 edition support)\n- Cargo (included with Rust)\n\n### Installing the Binaries\n\n#### Option 1: From crates.io (recommended)\n```bash\ncargo install i-ching\n```\n\n#### Option 2: From source\n```bash\ngit clone https://github.com/threemachines/i-ching.git\ncd i-ching\ncargo install --path .\n```\n\n#### Option 3: Build without installing (development)\n```bash\ngit clone https://github.com/threemachines/i-ching.git\ncd i-ching\ncargo build --release\n```\n\nBinaries will be in `./target/release/` directory.\n\n### Binaries Created\n\nAll installation methods create two binaries:\n- `i-ching` - CLI tool\n- `i-ching-mcp-server` - MCP server for Goose and Claude Code\n\nThe binaries include embedded data files, so they work anywhere without requiring external data files.\n\n### Verify PATH Configuration\n\n**Important for MCP usage (Goose & Claude Code)**: The `i-ching-mcp-server` binary must be in your PATH.\n\nCheck if `~/.cargo/bin` is in your PATH:\n\n```bash\necho $PATH | grep -q \"$HOME/.cargo/bin\" && echo \"✓ Cargo bin is in PATH\" || echo \"✗ Cargo bin is NOT in PATH\"\n```\n\nIf it's **not** in your PATH, add it to your shell configuration:\n\n```bash\n# For zsh (macOS default)\necho 'export PATH=\"$HOME/.cargo/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n\n# For bash\necho 'export PATH=\"$HOME/.cargo/bin:$PATH\"' >> ~/.bash_profile\nsource ~/.bash_profile\n```\n\n**Note**: If you installed Rust via Homebrew (rather than rustup), `cargo install` still puts binaries in `~/.cargo/bin`, which may not be in your PATH by default.\n\n## CLI Usage\n\n### Basic Usage\n\n```bash\n# Random reading using three coins method\ni-ching\n\n# Get help\ni-ching --help\n```\n\n### Input Formats\n\nThe CLI supports multiple input formats via the `--input` flag:\n\n```bash\n# Hexagram number (1-64)\ni-ching --input 1\n\n# Unicode hexagram character\ni-ching --input ䷀\n\n# Line numbers (6,7,8,9 format)\ni-ching --input \"7,8,9,6,7,8\"\n\n# Changing hexagram notation\ni-ching --input \"32→34\"\ni-ching --input \"32->34\"\ni-ching --input \"䷟→䷡\"\n```\n\n### Output Formats\n\nControl output format with the `--format` flag:\n\n```bash\n# Brief format (default for quick reference)\ni-ching --format brief --input 1\n# Output: ䷀ 1 Initiating\n\n# Full format with complete interpretations\ni-ching --format full --input 1\n\n# JSON format for programmatic use\ni-ching --format json --input 1\n\n# Numbers only (traditional line values)\ni-ching --format numbers --input 1\n# Output: [8, 8, 8, 8, 8, 8]\n\n# MOTD format (all caps, for system messages)\ni-ching --format motd --input 1\n# Output: ䷀ 1 INITIATING\n```\n\n## Goose Extension Setup\n\n**Prerequisites**: Complete [Installation](#installation) above first.\n\n### Enable in Goose\n\n1. Open Goose Desktop\n2. Go to **Extensions** (top-level menu item)\n3. Click **Add Custom Extension**\n4. Fill in the extension details:\n   - **ID**: `i-ching` (or your preferred identifier)\n   - **Name**: `I Ching Divination`\n   - **Description**: `I Ching divination readings with Wilhelm-Baynes translation`\n   - **Type**: `STDIO`\n   - **Command**: `i-ching-mcp-server`\n\n5. Click **Save** to add the extension\n6. Enable the extension by toggling it on in the Extensions list\n\n### Using in Goose\n\nIf the extension is enabled, Goose should be able to find and use it. The phrase \"conduct a divination\" or the keywords \"augur\" and \"auspicious\" seem to be enough in Claude models, while GPT seems to need you to more specifically namedrop the I Ching. (I would love more anecdata on how it works with different models - please open an issue or a PR modifying this README with your experiences.)\n\n## Claude Code Setup\n\n**Prerequisites**: Complete [Installation](#installation) above first, including the PATH verification step.\n\nThis repository includes a Claude Code plugin configuration (`.claude-plugin/` and `.mcp.json`) that enables I Ching divination directly in Claude Code.\n\n### Load the Plugin\n\nStart Claude Code with the plugin directory flag:\n\n```bash\nclaude --plugin-dir /path/to/i-ching\n```\n\nOr, if you cloned this repo to your home directory:\n\n```bash\nclaude --plugin-dir ~/i-ching\n```\n\n### Grant Permissions\n\nOn first use, Claude Code will ask for permission to:\n1. Load the plugin\n2. Use the MCP server tools (shown with a `plugin:i-ching:i-ching` prefix)\n\nThis is normal security behavior. Grant both permissions to enable divination.\n\n### Using with Claude Code\n\nOnce loaded, Claude Code can perform I Ching divinations. You can:\n- Ask for divination: \"Please conduct an I Ching reading for me\"\n- Request specific interpretations: \"What does hexagram 1 mean?\"\n- Use traditional language: \"I need an augury about my travel preparations\"\n\nThe AI will automatically use the `cast_hexagram` tool to generate readings and `interpret_reading` to provide the complete Wilhelm-Baynes text and interpretation.\n\n### Troubleshooting\n\n**MCP server failed to start**\n\nIf you see \"1 MCP server failed\" in Claude Code:\n\n1. Verify the binary is in your PATH (see [Installation - Verify PATH Configuration](#verify-path-configuration)):\n   ```bash\n   which i-ching-mcp-server\n   ```\n\n   If this returns \"not found\", you need to add `~/.cargo/bin` to your PATH.\n\n2. Verify the binary was installed:\n   ```bash\n   ls -la ~/.cargo/bin/i-ching-mcp-server\n   ```\n\n3. Check Claude Code debug logs:\n   ```bash\n   tail -100 ~/.claude/debug/latest | grep -i \"i-ching\\|mcp\"\n   ```\n\n**Plugin not loading**\n\nMake sure you're using the `--plugin-dir` flag when starting Claude Code and pointing it to the directory containing `.claude-plugin/plugin.json`.\n\n## MCP Server Usage\n\nThe MCP server can be used directly with any MCP-compatible client:\n\n```bash\n./target/release/i-ching-mcp-server\n```\n\n### Available Tools\n\n#### `cast_hexagram`\n- **Purpose**: Cast a new I Ching reading\n- **Parameters**: \n  - `lines` (optional): Array of 6 line values [6,7,8,9] to specify exact reading\n  - `method` (optional): Divination method (currently only \"coins\" supported)\n- **Returns**: Complete reading with hexagram details and interpretations\n\n#### `interpret_reading`\n- **Purpose**: Get detailed interpretation of a hexagram\n- **Parameters**:\n  - `hexagram`: Primary hexagram number (1-64)\n  - `changing_lines` (optional): Array of changing line positions [1-6]\n  - `transformed_hexagram` (optional): Transformed hexagram number\n- **Returns**: Detailed interpretation including meanings, judgments, and line interpretations\n\n## Divination Method\n\nThis tool uses the **three coins method** for divination, which has been widely used since the Song Dynasty (960-1279 CE). Each line is determined by tossing three coins:\n\n- **3 heads (HHH)**: Old Yang (9) - changing line\n- **2 heads, 1 tail**: Young Yin (8) - stable line  \n- **1 head, 2 tails**: Young Yang (7) - stable line\n- **3 tails (TTT)**: Old Yin (6) - changing line\n\n### On Yarrow Stalks\n\nI chose to not support yarrow-stalk readings for several reasons:\n\n* The separation of the stalks could be emulated with a probability curve, but I don't have any data I trust about how to calibrate that curve.\n* The separation is a volitional act that presents some philosophical challenges for automating. I think there's an argument that, as the augur, Goose could \"choose\" how to divide the stalks by seeding the RNG, but this seems sketchy and would still need the abovementioned probability curve.\n* Because this is written in Rust, I have some concerns that compiler optimizations could disrupt the form of the rites. For example, although the code could represent starting with 50 stalks and removing one at the beginning of the casting, the compiler might simplify this to simply starting with 49 stalks, which would be unacceptable.\n\nFuture versions _could_ allow for an MCP user to conduct their own reading and merely input the numeric results for AI interpretation, if there's demand.\n\n## Data Source\n\nThis project uses the Wilhelm-Baynes translation of the I Ching, which is considered one of the most authoritative English translations. The data includes:\n\n- **64 hexagrams** with names, Chinese characters, and pinyin\n- **Judgments** with full commentary\n- **Images** with interpretations\n- **Line interpretations** for all 384 individual lines\n- **Trigram information** and relationships\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── lib.rs              # Library root\n├── cli.rs              # CLI interface and formatting\n├── bin/\n│   ├── main.rs         # CLI binary\n│   └── mcp_server.rs   # MCP server binary\n└── core/\n    ├── mod.rs          # Core module exports\n    ├── data.rs         # Data loading and structures\n    ├── divination.rs   # Divination logic (coin tossing)\n    └── reading.rs      # Reading representation and methods\n```\n\n### Running Tests\n\n```bash\ncargo test\n```\n\n### Updating\nUpdate the version in `Cargo.toml`. This version number is also published by the MCP itself.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgements\n\nLovingly vibecoded in Goose with claude-4-sonnet.\n\nThis project would not have been possible without [adamblvck's dataset of the Wilhelm-Baynes](https://github.com/adamblvck/iching-wilhelm-dataset) text of the _I Ching_, and of course thanks are also due to Richard Wilhelm and Cary F. Baynes for producing their translation.\n\nSpecial thanks to John Minford, whose _I Ching_ translation I quite like, and which provided invaluable guidance on correctly enacting the _rites_. (Although I acknowledge his objection to digital methods.)\n\nThis project was originally inspired by [a skeet from Hazel Weakly](https://bsky.app/profile/hazelweakly.me/post/3lulqskpatk2x).\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## Support\n\nIf you encounter any issues or have questions, please file an issue on the GitHub repository.\n",
  "bytes": 11433,
  "sha": "22186febef7dd55ac3fc6bf999f0337a463b2eff0929d52d32239cf0b93be42e",
  "repo_slug": "threemachines/i-ching",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_threemachines_i_ching_i_ching_d38b274a/readme"
}