token-guardian 0.1.0b1

CLI-first guardrail for prompt token, cost, and context observability.

Token Guardian

Token Guardian is a CLI-first preflight guardrail for LLM prompts.

   _______    _                 _____                     _ _
  |__   __|  | |               / ____|                   | (_)
     | | ___ | | _____ _ __   | |  __ _   _  __ _ _ __ __| |_  __ _ _ __
     | |/ _ \| |/ / _ \ '_ \  | | |_ | | | |/ _` | '__/ _` | |/ _` | '_ \
     | | (_) |   <  __/ | | | | |__| | |_| | (_| | | | (_| | | (_| | | | |
     |_|\___/|_|\_\___|_| |_|  \_____|\__,_|\__,_|_|  \__,_|_|\__,_|_| |_|

                            [ shielded prompt preflight ]

Before any real model call, it shows:

• estimated tokens
• estimated cost
• context usage
• context risk
• prompt reduction hints

Then it shows the analysis before the execution flow continues.

Preview

Token Guardian opens with an interactive terminal flow that lets developers choose a host profile, select a model, submit a prompt, and inspect the preflight analysis before any real LLM call.

Release Status

Current release: 0.1.0-beta.1

This project is ready for early adopters who want to test a prompt guardrail in real workflows. It is not yet positioned as a fully hardened enterprise product.

What It Is

Token Guardian helps developers inspect a prompt before it reaches an LLM.

It is designed to answer three questions quickly:

• how many tokens this prompt is likely to use
• how much this prompt may cost
• whether this prompt is too large, noisy, or risky for the selected model context

Who It Is For

• developers using LLMs in daily coding workflows
• teams that want a simple prompt review step before execution
• open-source users who want a local, cross-platform CLI

What It Does Not Do

• it does not intercept every editor chat automatically
• it does not enforce organization-wide policy remotely
• it does not replace provider-side safety systems
• it does not depend on MCP or VS Code integration as a product requirement

Why CLI First

This is the most reliable way to enforce a real preflight gate:

• it works on Windows, macOS, and Linux
• it does not depend on editor-specific chat hooks
• it always shows the analysis before any real LLM call
• it is easy to share with other developers

Install

Windows

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

macOS / Linux

bash scripts/install.sh

Run

Windows

powershell -File scripts\run-cli.ps1

macOS / Linux

bash scripts/run-cli.sh

You can also run the command directly:

token-guardian

What the menu does

When the CLI opens, you get a simple menu:

1. revisar prompt
2. revisar prompt e enviar para LLM
3. ver metricas
4. listar modelos suportados
5. sair

The intended flow is:

1. choose the host profile such as Claude Code, Codex, or GitHub Copilot
2. choose a suggested model for that profile
3. paste the prompt and press Enter
4. inspect the markdown analysis
5. if you are in execution mode, Token Guardian continues to the LLM automatically

In the interactive terminal flow, selections use espaco to mark and Enter to confirm.

Prompt UX in the current menu:

• the prompt is entered in a single step
• Enter sends the prompt
• output token estimation is automatic in the interactive flow

Main commands

The interactive menu is the default, but advanced commands are still available:

token-guardian
token-guardian menu
token-guardian models
token-guardian metrics
token-guardian review --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."

Real LLM invocation

If you want Token Guardian to call the provider after the analysis step, install the gateway extra:

pip install -e .[gateway]

Then use:

token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."

The run flow analyzes first and then calls the LLM directly.

Metrics and observability

Token Guardian stores local usage data in SQLite.

Tracked data includes:

• total requests
• total tokens
• estimated cumulative cost
• most used models
• most used providers

Database file:

• token_guardian.db

To inspect metrics:

token-guardian metrics

Supported models

See the live list from the CLI:

token-guardian models

Developer commands

Run the full test suite:

pytest

License

MIT