2026-01-04 16:34:28 -07:00

22 KiB

Raw Permalink Blame History

Numerology Calculator

A comprehensive TypeScript-based numerology calculator with 10 specialized tools for deep numerological analysis. Calculate core numbers, find optimal days, analyze relationships, optimize names for master numbers, and integrate with the Telos personal development framework.

Built with Bun + TypeScript. Zero dependencies. Professional-grade calculations and interpretations.

Features

Core Calculations

Life Path Number - Your life's purpose and journey
Expression Number - Your natural talents and abilities
Soul Urge Number - Your inner desires and motivations
Birthday Number - Special gifts from your birth day
Advanced Numbers - Maturity, Personality, Hidden Passion, Karmic Lessons, Balance
Master Number Detection - Automatically identifies 11, 22, and 33

Timing & Cycles

Personal Cycles - Year/Month/Day calculations for strategic planning
Universal Cycles - Current world energy influences
Optimal Days Finder - Find best days for launches, creative work, business deals
Year-Ahead Calendar - 12-month Personal Month preview
Life Pinnacles - 4 major life stages with challenge numbers

Analysis Tools

Compatibility Analysis - Compare charts for romantic, business, family, or friendship relationships
Name Change Analyzer - Test how nicknames, stage names, or married names shift your energy
Name Optimizer 🔮 - "Rainbow tables" for finding master number variations (90+ name tests)
Telos Integration - Weekly planner aligning personal goals with daily numerology energy

Output & Formats

Multiple Output Formats - Terminal (with colors), Markdown, JSON
Detailed Interpretations - Comprehensive meanings for every number
Professional Reports - Ready for clients or personal deep-dive analysis

Core Numbers Explained

Life Path Number

Calculated from your complete birthdate (month + day + year), this is your primary number representing your life's purpose, the path you're meant to walk, and the lessons you're here to learn.

Expression Number

Calculated from your full name, this represents your natural talents, abilities, and the tools you have to fulfill your Life Path. It's what you're naturally good at.

Soul Urge Number

Calculated from the vowels in your name, this represents your inner desires, motivations, and what truly drives you at a soul level.

Birthday Number

Calculated from your day of birth, this represents special gifts and talents you were born with. It's a modifier that adds nuance to your other numbers.

Installation

git clone https://github.com/rpriven/numerology.git
cd numerology
# No dependencies to install - uses Bun's native TypeScript support!

Profile Management ⭐ NEW

Save your numerology profile once and reuse it across all tools. No more typing your name and birthdate every time!

Create a Profile

# Auto-generate profile ID from first name
bun profile.ts create --name "John Smith" --birthdate "3/15/1990"
# → Creates profile 'john'

# Custom profile ID
bun profile.ts create johns --name "John Smith" --birthdate "3/15/1990"

Manage Profiles

# List all profiles
bun profile.ts list

# Show profile details
bun profile.ts show rob

# Delete a profile
bun profile.ts delete rob

Use Profiles Everywhere

Once created, use --profile flag with any tool:

# Main calculator
bun numerology.ts --profile john --detailed --advanced --cycles

# PDF Report generator
bun generate-report.ts --profile john

# Compatibility analysis
bun compatibility.ts --profile john --person2 "Jane:1/1/1990"

# Optimal days finder
bun optimal-days.ts --profile john --day 1

# Year-ahead calendar
bun year-ahead.ts --profile john

# And all other tools...

Benefits:

Save multiple profiles (you, partner, family, clients)
No more retyping name/birthdate
Consistent data across all tools
Profiles stored in ~/.numerology/profiles/

Usage

Basic Calculation

# Terminal output with colors
bun numerology.ts --name "John Doe" --birthdate "5/13/1982"

# Detailed terminal output
bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --detailed

Output Formats

# Markdown format
bun numerology.ts --name "Jane Smith" --birthdate "11/22/1990" --format markdown

# JSON format
bun numerology.ts --name "Bob Jones" --birthdate "3/14/1975" --format json

# Save to file
bun numerology.ts --name "Alice Wonder" --birthdate "7/7/1977" --format markdown > profile.md

Timing Cycles

Calculate your Personal and Universal timing cycles:

# Show today's cycles
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --cycles

# Check cycles for specific date
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --cycles --date "12/25/2025"

# Detailed chart + cycles
bun numerology.ts --name "Your Name" --birthdate "mm/dd/yyyy" --detailed --cycles

Telos Integration

Export Numerology Profile

Generate telos-formatted numerology profile:

# Export numerology profile
bun telos-export.ts --name "Your Name" --birthdate "mm/dd/yyyy" > ~/.claude/context/personal/telos/numerology.md

Weekly Planner

Align your telos goals with Personal Day cycles for optimal timing:

# Generate this week's planner
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy"

# Plan specific week
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy" --week-start "10/14/2025"

# Use custom telos file
bun telos-week.ts --name "Your Name" --birthdate "mm/dd/yyyy" --telos-file ~/my-telos.md

Example Output:

╔════════════════════════════════════════════════════════════════╗
║  📅 YOUR WEEK AHEAD (10/14-20, 2025)                          ║
╚════════════════════════════════════════════════════════════════╝

Monday, October 14 - Personal Day 3
═══════════════════════════════════════════════════════════════
🎨 ENERGY: Expression, Creativity, Communication

🎯 TELOS GOAL ALIGNMENT (High Priority):
   ✅ G2: Provide education materials
   ✅ PJ3: Content creation and social media

⚠️  AVOID TODAY:
   ❌ Deep analytical work (save for Day 7)
   ❌ Heavy organizational tasks (save for Day 4)

This integrates with the Telos personal development framework.

Command Line Options

numerology.ts

--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--format FORMAT      Output format: terminal, markdown, json (default: terminal)
--detailed, -d       Show detailed meanings (terminal format only)
--cycles, -c         Include timing cycles (Personal Year/Month/Day)
--date DATE          Specific date for cycles (mm/dd/yyyy) [default: today]
--help, -h           Show help message

telos-export.ts

--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--help, -h           Show help message

telos-week.ts

--name NAME          Full name (required)
--birthdate DATE     Birthdate in mm/dd/yyyy format (required)
--week-start DATE    Week start date (mm/dd/yyyy) [default: next Monday]
--telos-file PATH    Path to telos.md file [default: ~/.claude/context/personal/telos/telos.md]
--help, -h           Show help message

optimal-days.ts ✨ NEW

--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--month NUMBER       Month to search (1-12) [optional - searches whole year if omitted]
--year NUMBER        Year to search [default: current year]
--day NUMBER         Target Personal Day number (1-9, 11, 22, 33)
--activity NAME      Activity type (new, creative, business, study, etc.) [optional]
--help, -h           Show help message

pinnacles.ts ✨ NEW

--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--name NAME          Your name [optional - for context]
--help, -h           Show help message

compatibility.ts ✨ NEW

--person1, --p1      First person (format: "Name:mm/dd/yyyy") [required]
--person2, --p2      Second person (format: "Name:mm/dd/yyyy") [required]
--type, -t           Relationship type: general, romantic, business, family, friendship [default: general]
--help, -h           Show help message

year-ahead.ts ✨ NEW

--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--year NUMBER        Year to preview [default: current year]
--name NAME          Your name [optional - for personalized output]
--help, -h           Show help message

advanced-numbers.ts ✨ NEW

--name NAME          Your full name [required]
--birthdate DATE     Your birthdate (mm/dd/yyyy) [required]
--detailed, -d       Show detailed interpretations
--help, -h           Show help message

name-change.ts ✨ NEW

--birthdate DATE         Your birthdate (mm/dd/yyyy) [required]
--current NAME           Your current/legal name [required]
--alternative NAME       Alternative name to compare [can use multiple times]
--help, -h               Show help message

name-optimizer.ts 🔮 NEW

--birthdate DATE         Your birthdate (mm/dd/yyyy) [required]
--current NAME           Your base name [required]
--find-masters           Find ANY master numbers (11, 22, 33)
--purpose TYPE           Optimize for: spiritual, business, creative, teaching, analytical
--target-expression NUM  Find specific Expression number
--target-soul-urge NUM   Find specific Soul Urge number
--max NUMBER             Max results to show [default: 20]
--help, -h               Show help message

Examples

Example 1: Quick Check

$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982"

╔═══════════════════════════════════════╗
║     NUMEROLOGY CHART                  ║
╚═══════════════════════════════════════╝

Name: John Doe
Birthdate: 5/13/1982

Core Numbers:
  1. Life Path:    11
  2. Expression:   8
  3. Soul Urge:    8
  4. Birthday:     4

Example 2: Detailed Analysis

$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --detailed

[Full detailed output with meanings for all numbers...]

Example 3: JSON for Integration

$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --format json
{
  "name": "John Doe",
  "birthdate": "5/13/1982",
  "lifePath": 11,
  "expression": 8,
  "soulUrge": 8,
  "birthday": 4,
  "calculations": {
    "month": 5,
    "day": 4,
    "year": 2,
    "nameBreakdown": {
      "John": 2,
      "Doe": 11
    },
    "vowelBreakdown": {
      "John": 6,
      "Doe": 11
    }
  },
  "meanings": {
    "lifePath": { ... },
    "expression": { ... },
    "soulUrge": { ... },
    "birthday": { ... }
  }
}

Example 4: Find Optimal Days

# Find all Personal Day 1 days in November 2025 (best for launches)
$ bun optimal-days.ts --birthdate "5/13/1982" --month 11 --year 2025 --day 1

# Find creative work days by activity type
$ bun optimal-days.ts --birthdate "5/13/1982" --month 12 --activity creative

# Find business deal days for entire year
$ bun optimal-days.ts --birthdate "5/13/1982" --year 2025 --day 8

Example 5: Life Stages & Pinnacles

# See your life pinnacles and current stage
$ bun pinnacles.ts --birthdate "5/13/1982" --name "John Doe"

# Output shows:
# - 4 major life pinnacles (9-year cycles)
# - Challenge numbers for each stage
# - Current pinnacle with strategic guidance
# - Next pinnacle preview

Example 6: Relationship Compatibility

# General compatibility analysis
$ bun compatibility.ts --person1 "John Doe:5/13/1982" --person2 "Jane Smith:11/22/1990"

# Romantic relationship analysis
$ bun compatibility.ts --p1 "Alice:7/7/1988" --p2 "Bob:3/14/1985" --type romantic

# Business partnership analysis
$ bun compatibility.ts --p1 "Sarah:1/1/1980" --p2 "Mike:8/8/1983" --type business

Example 7: Year-Ahead Calendar

# Preview current year's Personal Month cycles
$ bun year-ahead.ts --birthdate "5/13/1982"

# Plan for 2026 with name
$ bun year-ahead.ts --birthdate "5/13/1982" --year 2026 --name "John Doe"

# Output shows:
# - Personal Year theme and overview
# - All 12 months with Personal Month numbers
# - Strategic planning guide (launch months, creative months, etc.)
# - Key opportunities grouped by cycle type

Example 8: Advanced Numbers

# Calculate additional numbers beyond core 4
$ bun advanced-numbers.ts --name "John Doe" --birthdate "5/13/1982"

# With detailed interpretations
$ bun advanced-numbers.ts --name "Jane Smith" --birthdate "11/22/1990" --detailed

# Or use --advanced flag with main calculator for everything
$ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --advanced

# Output shows:
# - Maturity Number (who you become after age 40)
# - Personality Number (how others see you)
# - Hidden Passion Number (your secret talent)
# - Karmic Lessons (areas to develop)
# - Balance Number (how you handle crisis)

Example 9: Name Change Analysis

# Compare name variations
$ bun name-change.ts --birthdate "1/1/1980" --current "John Smith" --alternative "John Smith"

# Test multiple alternatives
$ bun name-change.ts -b "5/13/1982" -c "Jane Smith" -a "Jane Doe" -a "J Smith" -a "JJ"

# Output shows:
# - Expression/Soul Urge/Personality shifts
# - Master number activations
# - Karmic lesson changes
# - Energy shift analysis
# - Recommendations for which contexts to use each name

Example 10: Name Optimizer (Rainbow Tables) 🔮

# Find ANY master numbers
$ bun name-optimizer.ts -b "1/1/1980" -c "John Smith" --find-masters

# Optimize for spiritual writing pseudonym
$ bun name-optimizer.ts -b "5/13/1982" -c "Jane Smith" --purpose spiritual

# Find business power names (Expression 8)
$ bun name-optimizer.ts -b "3/14/1985" -c "John Doe" --target-expression 8

# Creative work optimization
$ bun name-optimizer.ts -b "7/7/1990" -c "Sarah Jones" --purpose creative

# Output shows:
# - Tests 90+ intelligent name variations
# - Finds master number combinations (11, 22, 33)
# - Scores and ranks results by purpose
# - Shows top matches with star ratings ⭐
# - Like "hash cracking" but for numerology!

Master Numbers

The calculator automatically detects and preserves master numbers (11, 22, 33) during calculation. Master numbers are spiritually significant and are not reduced to single digits.

Example:

✨ Master number found in Life Path: 11

Numerology Meanings Database

The calculator includes comprehensive meanings for each number covering:

Keywords
Full description
Strengths
Challenges
Life purpose
Career paths
Relationship dynamics
Spiritual lessons

Each number (1-9, 11, 22, 33) has contextual meanings that vary based on position:

Life Path meanings (your core purpose)
Expression meanings (your natural talents)
Soul Urge meanings (your inner desires)
Birthday meanings (your special gifts)

How Numerology Works

Numerology is based on the Pythagorean system where:

Each letter has a numeric value (A=1, B=2, ... Z=26)
Numbers are reduced to single digits (or master numbers)
Different calculations reveal different aspects of personality

Calculation Methods:

Life Path = Reduce(Month) + Reduce(Day) + Reduce(Year), then reduce sum
Expression = Sum of all letters in full name, reduced
Soul Urge = Sum of vowels in full name, reduced
Birthday = Day of birth, reduced

Master Number Rule: 11, 22, and 33 are never reduced further.

File Structure

numerology/
├── core-calculator.ts             # Core calculation functions
├── meanings.ts                    # Comprehensive numerology interpretations
├── cycle-meanings.ts              # Timing cycle interpretations
├── cycles.ts                      # Timing cycle calculations
├── numerology.ts                  # Main calculator with CLI
├── generate-report.ts             # LaTeX PDF report generator 📄 NEW
├── profile.ts                     # Profile management CLI ⭐ NEW
├── profile-manager.ts             # Profile CRUD operations ⭐ NEW
├── telos-export.ts                # Telos framework integration
├── telos-week.ts                  # Weekly planner (goals + cycles)
├── telos-cycles-analyze.ts        # Goal alignment analyzer
├── optimal-days.ts                # Find best days for activities ✨
├── pinnacles.ts                   # Life stages & pinnacles calculator ✨
├── compatibility.ts               # Relationship compatibility analyzer ✨
├── year-ahead.ts                  # Year-ahead Personal Month calendar ✨
├── advanced-numbers.ts            # Additional numbers (Maturity, Personality, etc.) ✨
├── name-change.ts                 # Name variation comparison tool ✨
├── name-optimizer.ts              # Master number hunter (rainbow tables) 🔮
├── templates/
│   └── report-template.tex        # LaTeX report template
├── archive/
│   ├── numerology.py              # Original Python version
│   ├── r_num.py                   # Refactored Python version
│   └── requirements.txt           # Python dependencies
├── CYCLES-DOCUMENTATION.md        # Complete cycle system guide
├── TELOS-INTEGRATION.md           # Integration vision document
├── PROFILE-SYSTEM.md              # Profile management documentation
└── README.md                      # This file

Technology Stack

Runtime: Bun (fast TypeScript runtime)
Language: TypeScript (type-safe, modern)
No Dependencies: Pure TypeScript, no external packages required

Development

The calculator is written in pure TypeScript with no external dependencies. It uses:

Bun's native TypeScript support
Standard library only
ANSI escape codes for terminal colors
Functional programming patterns

Documentation

CYCLES-DOCUMENTATION.md - Complete guide to timing cycles
TELOS-INTEGRATION.md - Telos integration vision and roadmap

Roadmap

Phase 1: Core Integration ✅

Build telos-week.ts weekly planner
Test with real telos data
Document timing cycles system
Update README

Phase 2: Deep Analysis ✅

Build telos-cycles-analyze.ts - Goal alignment analyzer with scoring
Quarterly action plan generator
2026 preview feature

Phase 3: Fabric Integration ✅

Create t_numerology_guidance Fabric pattern
AI-powered combined analysis
Integrate with telos-runner.ts

Phase 4: Advanced Features ✅

Optimal days finder (find best days for specific activities) ✨
Life stages/pinnacles calculator ✨
Compatibility analysis (compare two charts) ✨
Year-ahead calendar (Personal Month overview for 12 months) ✨

Phase 5: Polish ✅

Additional numbers (Maturity, Hidden Passion, Karmic Lessons, etc.) ✨
Name change analysis (compare name variations) ✨
Name optimizer (brute-force master numbers) 🔮

Phase 6: Profile System & Ultimate Deliverable ✅ COMPLETE

Profile management system (save name/birthdate, reuse across all tools)
- bun profile.ts create --name "..." --birthdate "..."
- bun numerology.ts --profile name [command]
- Store in ~/.numerology/profiles/
- Multiple profiles support (you, partner, clients)
- ALL major tools now support --profile flag
📄 LaTeX PDF Report Generator - The ultimate deliverable!
- Beautiful full-spectrum numerology report
- Core numbers + advanced numbers + cycles + pinnacles
- Professional typography and layout
- Includes all calculations and detailed interpretations
- Shareable/printable for clients or personal use
- bun generate-report.ts --profile name

🎯 CURRENT STATUS: Production-ready for client delivery via PDF reports

Phase 7: Future Enhancements (Post-Customer Validation)

Strategy: Start with PDF reports as primary deliverable. Gather customer feedback and traction. Then expand to web UI for self-service.

Calculation Enhancements

Transits Calculator - Calculate when you'll experience specific Personal Days/Months/Years
Karmic Debt Numbers - Detect and interpret 13, 14, 16, 19 karmic debt numbers
Master Number 44 - Add support for master number 44
Compound Numbers - Track compound numbers before reduction (e.g., 29/11 vs 38/11)
Business Name Analysis - Dedicated tool for business/brand name numerology
Pythagorean vs Chaldean - Toggle between different numerology systems

Intelligence & Optimization

Business Name Generator - Intelligent variations beyond middle initials for optimal numbers
Multi-person Compatibility - Compare 3+ people (teams, families, partnerships)

User Experience & Delivery

🎨 Web UI (Bun.serve + React) - Deploy after customer traction
- Interactive forms with real-time calculations
- Visual comparisons and compatibility charts
- Side-by-side name variations explorer
- Shareable links and web-based PDF generation
- Profile/account management
- Date pickers and input validation
Interactive Birth Chart Visualization - Visual representation of numerology charts
Email Delivery - Automated email delivery of PDF reports to clients
Client Portal - Dashboard for managing multiple client reports

Credits

Original Python Implementation: Initial algorithm and calculation logic TypeScript Rewrite: Modern implementation with comprehensive meanings database Numerology System: Based on Pythagorean numerology

License

GNU General Public License v3.0

Resources

Made with ❤️ and TypeScript

22 KiB Raw Permalink Blame History