Horace-Maxwell/horosa-skill

What it solves

Horosa Skill provides a local-first interface for AI agents to access 106 professional astrology and metaphysics techniques. It prevents AI "hallucinations" in metaphysical readings by replacing the AI's attempt to calculate charts or interpret rules from memory with a deterministic, local runtime that provides structured, traceable data.

How it works

The project acts as an MCP (Model Context Protocol) server and CLI that bridges AI clients (like Claude Desktop or Cursor) to a headless JS engine and a Java/Python backend.

• Deterministic Runtime: Algorithms run locally (offline) to ensure calculations are identical to the professional Horosa desktop application.
• Clarification Gate: The system intercepts calls if critical parameters (time, location, timezone) are missing, forcing the AI to ask the user for confirmation rather than guessing.
• Structured Output: Every tool returns a unified "envelope" containing a snapshot of the chart and a "technique card" that documents the specific rules and versions used.
• Traceability: It includes a 31-domain knowledge base with 408 cited entries, ensuring that any interpretation provided by the AI can be traced back to a specific manual or rulebook.
• Faithfulness Benchmarking: A deterministic validator checks AI interpretations against the actual chart data to flag invented or contradicted facts.

Who it’s for

• AI developers building specialized metaphysical or astrological agents.
• Power users of AI clients who want professional-grade, local-first astrological calculations integrated into their LLM workflows.
• Practitioners who require high precision and traceability in metaphysical readings.

Highlights

• 106 Integrated Techniques: Covers Western astrology, Chinese metaphysics (Bazi, Ziwei, Qimen, etc.), and 14 types of "Shenshu" (divine numbers).
• Local-First & Offline: All calculations happen on the user's machine; no data is uploaded to the cloud.
• MCP Ready: Easy integration with Claude Code, Claude Desktop, Cursor, and Open WebUI.
• Anti-Hallucination Suite: Combines a clarification gate, a cited knowledge base, and a faithfulness evaluator to ensure AI accuracy.
• Multi-Technique Synthesis: The horosa_hecan tool allows parallel execution of multiple techniques to compare results and explicitly disclose divergences.