token-cost-guard 0.1.0

Track AI API token costs locally. Know your costs before the bill arrives.

Token Cost Guard

Know your AI costs before the bill arrives.

Track OpenAI and Anthropic API token costs locally. Never be surprised by runaway costs again.

The Problem

Building with AI APIs is amazing until you get the bill.

• No visibility into token consumption until charges appear
• Experiments cost money (sometimes thousands)
• No circuit breakers or alerts
• Manual tracking is tedious

Token Cost Guard solves this with local-first cost tracking that never sends data to the cloud.

Features

✅ Local SQLite - Your token data never leaves your machine
✅ One-line setup - client = track(OpenAI())
✅ Real-time tracking - Logs every API call automatically
✅ Cost breakdown - View costs by model, day, and session
✅ Threshold alerts - Slack/Discord webhooks when you hit limits
✅ CSV export - Share reports with your team

Installation

pip install git+https://github.com/alexcalderado/token-cost-guard.git

Note: If the token-guard command is not found after installation, add Python scripts to your PATH:

export PATH="$HOME/Library/Python/3.9/bin:$PATH"  # macOS
# or 
export PATH="$HOME/.local/bin:$PATH"  # Linux

Add this line to your shell profile (.zshrc, .bashrc, etc.) to make it permanent.

Quick Start

1. Initialize configuration:

token-guard init

2. Set your API keys:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

3. Wrap your client (one-line change):

from token_guard import track
from openai import OpenAI

# Before: client = OpenAI()
# After:
client = track(OpenAI())

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)
# Automatically logged to ~/.token-guard/guard.db

4. Check your costs:

token-guard report

Usage

View Cost Summary

token-guard report

╭──────────────────────────────╮
│  Token Cost Guard — Report   │
╰──────────────────────────────╯

Today's Cost:    $2.14
Last 30 Days:    $47.82

Top Models:
  gpt-4...................... $35.20
  claude-opus-4-5............. $12.62

Export to CSV

token-guard export --days 7
# Creates: token-cost-guard-export-2026-02-15.csv

Set Cost Alerts

token-guard alerts add --type daily_cost --threshold 10 \
  --webhook https://hooks.slack.com/services/YOUR/WEBHOOK

When daily costs exceed $10, you'll get a Slack notification.

View Model Pricing

token-guard config --pricing

Model Pricing (per 1M tokens):
  claude-sonnet-4-5................. $3.00 input, $15.00 output
  gpt-4o............................ $2.50 input, $10.00 output
  gpt-5.2........................... $1.75 input, $14.00 output

How It Works

Token Cost Guard wraps your AI client with a function that:

1. Calls the original API (no proxying, same latency)
2. Logs input/output tokens to local SQLite
3. Calculates cost based on model pricing
4. Returns the response unchanged

If logging fails, the API call still succeeds (graceful degradation).

Supported Models

• Anthropic: claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5
• OpenAI: gpt-5.2, gpt-5-mini, gpt-4.1, gpt-4.1-mini, gpt-4o

Privacy

✅ No cloud sync
✅ No accounts
✅ No third-party services

Your API cost data stays on your machine. Pricing is hardcoded and can be customized in ~/.token-guard/pricing.json.

v2 Roadmap

• Async/streaming support
• Local web dashboard
• Cost forecasting
• Optimization suggestions

Support

• GitHub: https://github.com/AlexCalderAI/token-cost-guard
• Issues: Report bugs or request features

---

Made by @AlexCalderAI · MIT License