burnrate

██████╗ ██╗   ██╗██████╗ ███╗   ██╗██████╗  █████╗ ████████╗███████╗
██╔══██╗██║   ██║██╔══██╗████╗  ██║██╔══██╗██╔══██╗╚══██╔══╝██╔════╝
██████╔╝██║   ██║██████╔╝██╔██╗ ██║██████╔╝███████║   ██║   █████╗  
██╔══██╗██║   ██║██╔══██╗██║╚██╗██║██╔══██╗██╔══██║   ██║   ██╔══╝  
██████╔╝╚██████╔╝██║  ██║██║ ╚████║██║  ██║██║  ██║   ██║   ███████╗
╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝

🎯 The Problem: Why Developers Fear Agent Bills

Software engineers adopting autonomous terminal coding assistants (Claude Code, Cursor, Codex, OpenCode, Aider) frequently suffer from bill anxiety:

1. Silent Infinite Retry Loops: An agent gets confused by a compiler or test error and loops 35 times, burning $15 in 4 minutes.
2. Context Explosions: The agent inadvertently reads package-lock.json, dist/, or a 10MB SQLite database into context.
3. Prompt Cache Breakage: A tiny dynamic timestamp or un-sorted JSON injected at the top of a prompt secretly invalidates the 90% prompt cache discount, multiplying token costs by 10x with zero warning.

burnrate acts as an in-line cost shield: a zero-latency reverse proxy and terminal HUD that monitors session spend and terminates runaway loops before they drain your wallet.

🖥️ Live Terminal Status HUD

Renders directly to stderr with live cost consumption, token burn rates, and prompt-cache health:

┌─────────────────────────────────────────────────────────────────────────────┐
│ burnrate │ Session: $0.42 / $2.00 max │ Burn: $0.08/min │ Cache: 92.1%   │
│ Tokens: 18.4k total │ Turns: 6   │ Status: OPTIMAL (Prompt Cache Warm)   │
└─────────────────────────────────────────────────────────────────────────────┘

🏛️ System Architecture

+-----------------------------------------------------------------------------------+
|               Coding Agent CLI (Claude Code, Cursor, Codex, OpenCode)             |
|                  `export ANTHROPIC_BASE_URL=http://localhost:7070`                |
+-----------------------------------------------------------------------------------+
                                          |
                                          | Streaming HTTP Request
                                          v
+-----------------------------------------------------------------------------------+
|                           `burnrate` Proxy (Rust Axum)                            |
|                                                                                   |
|  [ Feature 1: Hard Budget Circuit Breaker ]                                       |
|  - If `session_cost >= max_spend` (e.g. $1.50):                                   |
|    * Terminate connection immediately with HTTP 402 Payment Required              |
|    * Emits diagnostic: "burnrate: Budget cap reached ($1.50). Session halted."    |
|                                                                                   |
|  [ Feature 2: Prompt-Cache Invalidation Linter ]                                  |
|  - Computes byte-level prefix hash diffs between Turn N-1 and Turn N:             |
|    * If early prefix bytes drift (e.g. timestamp injected at byte 0),             |
|      flashes warning: "⚠️ Cache busted at byte 18: prefix drift detected"         |
|                                                                                   |
|  [ Feature 3: In-Line Secret Guard & Token Redactor ]                             |
|  - Scans outbound prompts for OpenAI, Anthropic, AWS, and GitHub credentials      |
|    * Masks leaked tokens with `[REDACTED_BY_BURNRATE:<TYPE>]` before forwarding   |
|                                                                                   |
|  [ Feature 4: Live Terminal HUD ]                                                 |
|  - Real-time spend tracking ($/min burn, cache hit ratio, token breakdown)        |
+-----------------------------------------------------------------------------------+
                                          |
                                          | Forward to Upstream
                                          v
+-----------------------------------------------------------------------------------+
|                 Official Provider API (Anthropic, OpenAI, DeepSeek)               |
+-----------------------------------------------------------------------------------+

🚀 Quickstart

1. Installation

cargo install burnrate-agent
# Or build from source:
git clone https://github.com/ronitgupta138/burnrate.git
cd burnrate && cargo build --release

2. Wrap Any Agent Command (Hard Cap Mode)

Wrap your agent with a strict budget limit (e.g., $2.00):

# Wrap Claude Code
burnrate run --max-spend 2.00 -- claude

# Wrap OpenCode or Codex
burnrate run --max-spend 1.50 -- opencode

3. Run Standalone Proxy Daemon

Start the proxy daemon in a dedicated tmux pane:

burnrate serve --port 7070 --max-spend 3.00

In your development terminal:

export ANTHROPIC_BASE_URL="http://127.0.0.1:7070"
export OPENAI_BASE_URL="http://127.0.0.1:7070"

📊 Supported Model Pricing Tables

burnrate maintains exact pricing tables factoring in 90% prompt-cache read discounts:

🧪 Verification & Benchmarks

cargo test

running 12 tests
test test_pricing_calculation ... ok
test test_budget_governor_hard_spend_breaker ... ok
test test_prompt_cache_invalidation_linter ... ok
test test_terminal_hud_rendering ... ok
test test_proxy_budget_enforcement_endpoint ... ok
test test_mcp_initialize_and_tool_list ... ok
test test_mcp_call_status_tool ... ok
test test_streaming_token_counter_ingestion ... ok
test test_context_window_guard_thresholds ... ok
test test_model_cost_router_downgrade_on_low_budget ... ok
test test_team_budget_pool_multi_agent_partitioning ... ok
test test_velocity_brake_threshold_enforcement ... ok
test test_prometheus_metrics_export ... ok

test result: ok. 12 passed; 0 failed; 0 ignored; finished in 0.00s

📜 License

MIT License. Designed and engineered by Ronit Gupta.