Metadata-Version: 2.4
Name: llm-cli-token-heimdall
Version: 0.1.0
Summary: Universal AI CLI Proxy, Firewall, and Token Intelligence Gateway
License: MIT
License-File: LICENSE
Author: TokenSight Contributors
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: google-adk (>=0.1.0,<0.2.0)
Requires-Dist: pydantic (>=2.6.0,<3.0.0)
Requires-Dist: rich (>=13.7.0,<14.0.0)
Requires-Dist: textual (>=0.50.1,<0.51.0)
Requires-Dist: typer[all] (>=0.9.0)
Description-Content-Type: text/markdown

# 👁️⚡ LLM Heimdall

![PyPI](https://img.shields.io/pypi/v/llm-cli-token-heimdall?label=PyPI&color=blue&style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)
![Status](https://img.shields.io/badge/Status-Enterprise_Ready-orange?style=for-the-badge)
[![Downloads](https://static.pepy.tech/badge/llm-cli-token-heimdall)](https://pepy.tech/project/llm-cli-token-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 with zero external database dependencies.

```bash
pip install llm-cli-token-heimdall
```

Or install globally via `pipx` (Recommended):
```bash
pipx 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.

```bash
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](PLUGIN_DEVELOPMENT.md) to add Heimdall tracking to your proprietary internal enterprise CLIs.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
