# 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 ```bash git clone [your-repo-url] 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 ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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](https://danielmiessler.com/p/telos/). ## 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 ```bash $ 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 ```bash $ bun numerology.ts --name "John Doe" --birthdate "5/13/1982" --detailed [Full detailed output with meanings for all numbers...] ``` ### Example 3: JSON for Integration ```bash $ 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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) 🔮 ```bash # 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:** 1. **Life Path** = Reduce(Month) + Reduce(Day) + Reduce(Year), then reduce sum 2. **Expression** = Sum of all letters in full name, reduced 3. **Soul Urge** = Sum of vowels in full name, reduced 4. **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](./CYCLES-DOCUMENTATION.md)** - Complete guide to timing cycles - **[TELOS-INTEGRATION.md](./TELOS-INTEGRATION.md)** - Telos integration vision and roadmap ## Roadmap ### Phase 1: Core Integration ✅ - [x] Build telos-week.ts weekly planner - [x] Test with real telos data - [x] Document timing cycles system - [x] Update README ### Phase 2: Deep Analysis ✅ - [x] Build telos-cycles-analyze.ts - Goal alignment analyzer with scoring - [x] Quarterly action plan generator - [x] 2026 preview feature ### Phase 3: Fabric Integration ✅ - [x] Create t_numerology_guidance Fabric pattern - [x] AI-powered combined analysis - [ ] Integrate with telos-runner.ts ### Phase 4: Advanced Features ✅ - [x] Optimal days finder (find best days for specific activities) ✨ - [x] Life stages/pinnacles calculator ✨ - [x] Compatibility analysis (compare two charts) ✨ - [x] Year-ahead calendar (Personal Month overview for 12 months) ✨ ### Phase 5: Polish ✅ - [x] Additional numbers (Maturity, Hidden Passion, Karmic Lessons, etc.) ✨ - [x] Name change analysis (compare name variations) ✨ - [x] Name optimizer (brute-force master numbers) 🔮 ### Phase 6: Profile System & Ultimate Deliverable ✅ COMPLETE - [x] 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** - [x] 📄 **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 - [Numerology Basics](https://www.numerology.com/) - [Life Path Calculator](https://www.tokenrock.com/numerology/life-path-number/) - [Telos Framework](https://danielmiessler.com/p/telos/) --- **Made with ❤️ and TypeScript**