👁️⚡ LLM Heimdall

Heimdall is the all-seeing Guardian of your API limits. It stands at the gate of your terminal, inspecting every single token trying to cross the bridge to OpenAI, Anthropic, or Google. If a developer unknowingly executes a wildly unoptimized prompt that blows your daily enterprise budget, Heimdall physically slams the gate shut and blocks the network execution.

Heimdall is a local, privacy-first Universal Token Intelligence Gateway. It seamlessly wraps your favorite AI CLIs (claude, gemini, cursor, openai) to act as an interceptor, cache-engine, and cost-firewall.

🔥 Why Run Heimdall?

1. 🛡️ Enterprise Budget Firewall: Set a hard daily budget (e.g. heimdall config 5.00). If a command costs $5.01, Heimdall aborts the execution before a single penny reaches the cloud.
2. 🧠 Semantic Prompt Caching: Why pay the LLM for the exact same prompt twice? Heimdall intercepts your prompts locally, hashes them, and returns $0.00 cached hits instantly.
3. ⚡ Pre-Flight Compression: If Heimdall detects massive files being uploaded to your terminal prompt, it pauses to automatically compress and optimize the text.
4. 📊 The God-Mode Dashboard: Visualize every penny your machine is spending on tokens broken down by Git Repository (Automatic Project Attribution).

⚡ Installation & Quick Start

Heimdall is deployed via PyPI. Because it is a standalone CLI application, we strongly recommend using pipx to install it globally without breaking your system's Python packages (avoids PEP 668 errors).

# Recommended global installation
pipx install llm-cli-token-heimdall

(If you know what you are doing and want to install it manually in a specific virtual environment, you can use pip install llm-cli-token-heimdall)

Install the Magic Shell Guard

Don't worry about remembering heimdall run. Our installer binds Heimdall directly into your terminal automatically.

heimdall init
heimdall install-aliases
source ~/.zshrc

Now, when you type claude "Refactor this module" or gemini "Explain gravity", the all-seeing Heimdall silently steps in to analyze your payload!

💻 Guard Commands

• heimdall run <tool> <args> - Intercept and track an AI command manually.
• heimdall dashboard - Launch the central Token UI.
• heimdall config <limit> - Set your absolute daily dollar firewall limit.
• heimdall export report.csv --days 30 - Data dump your analytics for management.
• heimdall update-pricing - Fetch the latest live pricing APIs for accurate cost tracking.

🔌 Expanding with Universal Adapters

Heimdall ships out of the box with auto-detected tracking for:

• 📝 Anthropic CLI (claude)
• 🤖 OpenAI / Codex CLIs (gpt, codex, openai)
• 🔮 Google Gemini CLI (gemini)
• ...and falls back to robust file-size estimation heuristics for literally any other tool.

Check the Plugin Development Guide to add Heimdall tracking to your proprietary internal enterprise CLIs.

License

This project is licensed under the MIT License - see the LICENSE file for details.