My Hermes agent spent $3 before I noticed. Now it can't.

This is a submission for the Hermes Agent Challenge.

I ran a Hermes research agent across 50 literature review tasks and forgot to check the bill until the next morning. Three dollars gone. The agent had retried a bunch of failed web searches and each retry cost money.

The fix is obvious in hindsight: track cost as you go and stop when you hit the limit. That's agent-cost-guard.

Raise when the limit hits

from agent_cost_guard import CostGuard

guard = CostGuard(limit_usd=1.00)

# Inside your agent loop:
response = client.messages.create(model="claude-sonnet-4-5", ...)
cost = calculate_cost(response.usage)
guard.add(cost, label="research_turn")  # raises CostLimitExceeded if over $1

Warn before it hits

def on_warn(w):
    log.warning(f"Cost at {w.pct_used:.0%} — ${w.total_usd:.4f} of ${w.limit_usd:.4f}")

guard = CostGuard(
    limit_usd=1.00,
    warn_at=[0.5, 0.8],
    on_warn=on_warn,
)

The callback fires once per threshold and never again unless you call guard.reset().

Track by label

guard.add(0.05, label="web_search")
guard.add(0.12, label="llm_synthesis")
guard.add(0.03, label="web_search")

s = guard.summary()
print(s.by_label)
# {"web_search": 0.08, "llm_synthesis": 0.12}

Now you know where the money went.

Keep going past the limit

guard = CostGuard(limit_usd=0.50, stop_on_limit=False)
guard.add(1.00)  # no exception
print(guard.ok)         # False
print(guard.remaining_usd)  # -0.50

Useful for logging-only mode when you want to measure but not block.

Check manually

guard.check()  # raises CostLimitExceeded if total > limit

Call it at checkpoints rather than after every single add.

Summary report

s = guard.summary()
print(str(s))
# Cost: $0.20 / $1.00 (20.0% used)
# Entries: 3
# Breakdown:
#   llm_synthesis: $0.12
#   web_search: $0.08

Factory with sensible defaults

from agent_cost_guard import make_cost_guard

guard = make_cost_guard(limit_usd=1.00, on_warn=on_warn)
# warn_at defaults to [0.5, 0.8]

Zero dependencies

Standard library only: dataclasses, time. Nothing else.

pip install agent-cost-guard

Repo: https://github.com/MukundaKatta/agent-cost-guard