https://github.com/ejfox/cli-ching
A CLI tool to guide and interpret I Ching throws
https://github.com/ejfox/cli-ching
Last synced: 2 months ago
JSON representation
A CLI tool to guide and interpret I Ching throws
- Host: GitHub
- URL: https://github.com/ejfox/cli-ching
- Owner: ejfox
- Created: 2024-08-11T17:58:54.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-25T17:18:41.000Z (over 1 year ago)
- Last Synced: 2025-03-19T20:05:32.569Z (about 1 year ago)
- Language: JavaScript
- Size: 32.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CLI-CHING
CLI-CHING is a command-line interface tool for consulting the I Ching (Book of Changes). It provides a digital means of casting hexagrams and receiving interpretations, blending ancient wisdom with modern technology. It does not cast for you, you must bring 3 coins and report their results back to the application, which will help you convert them into the correct line.
https://github.com/user-attachments/assets/133a7d1d-a4bc-4131-b675-4de0b2466ddb
## Features
- Simple command-line interface
- Flexible coin toss input
- **Natural RNG Mode**: Automatic hexagram generation using true random numbers from natural processes
- Random.org (atmospheric noise)
- ANU Quantum Random Numbers (quantum phenomena)
- Graceful fallback to pseudo-random if APIs unavailable
- Hexagram visualization
- AI-powered interpretations
- History of recent consultations
- Supports quick queries via command-line arguments
## Installation
1. Ensure you have Node.js installed on your system.
2. Clone this repository:
```
git clone https://github.com/yourusername/cli-ching.git
cd cli-ching
```
3. Install the required dependencies:
```
npm install
```
## Usage
### Basic Usage
Run the script with:
```
node index.js
```
Follow the prompts to enter your question and coin tosses.
### Quick Query
You can also start a consultation with a question directly from the command line:
```
node index.js -q "Will my project succeed?"
```
### Natural RNG Mode (Automatic Coin Tosses)
For a fully automated experience, use the `--auto` or `-a` flag to generate hexagrams using true random numbers from natural processes:
```
node index.js --auto -q "What should I focus on today?"
```
This mode uses:
1. **Random.org** - True random numbers generated from atmospheric noise
2. **ANU Quantum Random Numbers** - Random numbers from quantum phenomena (fallback)
3. **Pseudo-random generator** - Standard RNG if natural sources are unavailable
⚠️ **Important Note**: The traditional method of physically throwing coins is considered the proper and preferred way to consult the I Ching. The physical act of casting is an integral part of the divination process. The natural RNG mode should only be used when physical coins are not available.
## Coin Tossing
When prompted, enter the results of your coin tosses using T for tails and H for heads. For example:
- TTT (3 tails)
- TTH, THT, or HTT (2 tails, 1 head)
- THH, HTH, or HHT (1 tail, 2 heads)
- HHH (3 heads)
The order doesn't matter, so HTT is the same as TTH.
## Interpreting Results
The tool will display your hexagram, including any changing lines. It will then provide an AI-generated interpretation based on your question and the resulting hexagram.
## Configuration
CLI-CHING automatically saves your consultations to a `.iching-throws` file in your home directory. The three most recent consultations are displayed when you start the tool.
## Dependencies
- axios: For making HTTP requests to the AI interpretation service
- figlet: For generating ASCII art text
- readline: For handling user input (built into Node.js)
## AI Interpretation
The tool uses a local LLM (Language Model) running on `http://localhost:1234` for generating interpretations. Ensure your LLM server is running before using the interpretation feature.
## Customization
You can modify the `getInterpretation` function in `index.js` to use a different AI service or to implement your own interpretation logic.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.