floe-guard skill
Spend meter and budget gate for AI calls in Python and TypeScript: costs every vendor leg and stops a loop at the ceiling.
- 288 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The optional `floe-guard push` command sends priced spend events to hosted Floe.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/floe-guardDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The optional `floe-guard push` command sends priced spend events to hosted Floe.
This is third-party code. Review the repository files before installing.
What it does
floe-guard costs each agent call the moment it ends: model, speech-to-text, text-to-speech, telephony and paid tools. The spend ledger lives in the process, with no account and no telemetry by default. Before a call, `guard.check()` compares against a dollar ceiling and raises `BudgetExceeded` if the next call would cross it. After the call, `guard.record()` accrues the tokens. Adapters cover OpenAI, Anthropic, Gemini, CrewAI, LiteLLM, LangChain, LangGraph and the Pipecat, LiveKit, Vapi and Retell voice stacks. The repository ships `SKILL.md` and `AGENTS.md` so a coding agent can wire the guard itself.
Who it is for. Developers of agents and voice bots who need a hard spend ceiling and visible cost per call.
Good fit when
- An agent spins in a loop and must be stopped before the bill grows.
- A voice bot on Pipecat, LiveKit, Vapi or Retell has its call cost counted per stage.
- Paid agent tools are put under one ceiling with `reserve_tool()` and `settle_tool()`.
- A coding agent is asked to wire the guard from `SKILL.md` without hand edits.
Not a fit when
- You need a balance or real charges: the library holds a budget, not money.
- You need exact pricing at contract rates without a rate card: public list prices apply out of the box.
- You need spend tied to clients and campaigns locally: that exists only in the hosted Floe.
Example request
Wire floe-guard with a 5 dollar ceiling to the OpenAI calls in this project and show that `BudgetExceeded` is raised on overrun.Limitations
The bundled map holds public vendor list prices, so a rate stays unconfirmed until you set your own rate card. `record_tool()` meters after the call and cannot stop it; `reserve_tool()` and `settle_tool()` block beforehand. Coverage Score and 7-day history need a free key. `floe-guard push` sends only priced spend events, never prompts.
How to disable. Remove `check()` and `record()` from the code and uninstall `floe-guard` with pip or npm. Delete any ledger exported with `export_log()` separately.
FAQ
Is an account required?
No. The ledger lives in the process with no account and no telemetry by default. A free key is needed only for Coverage Score and 7-day history.
How is `check()` different from `max_tokens`?
`max_tokens` and `max_rpm` cap size and rate, not dollars, so a cheap model in a loop still drains the budget. `check()` stops the call by amount.
How do I set my own rates?
Create a rate card with your rates. It beats the bundled map; the order is per-call override, your rate card, public prices, then `UnpriceableLegError`.
What leaves the machine with `floe-guard push`?
Only priced spend events from the JSONL file exported with `guard.export_log()`. Prompts and content stay in the process.
Is there a TypeScript version?
Yes, `npm i floe-guard`: Vercel AI SDK middleware and LiveKit, Vapi and Retell adapters. The Python adapter set is wider.
Discussion
No questions or reviews yet.
Related
SkillsA local binary tracks Claude Code, Codex and Cursor spend from provider-billed tokens and enforces guardrails on your agents.
A skill that wires a whole-run spend cap into a Python agent and checks the budget before every model call to stop runaway cost.
A skill plus hooks that keep a coding agent on task and cut speculative defenses, unread checksums and scope creep
Local ledger of AI agent work: tokens, estimated cost, steps, changed files and checks per task for Claude Code, Codex and OpenCode
Microsoft Research and UC Berkeley plugin that cuts the cost of Claude Code, Codex and Copilot CLI sessions using earlier sessions
Local proxy between agent and model API: compresses diffs and logs, keeps the request prefix stable for prompt caching.
README in short
The guard runs in-process: the amount is checked before a call and accrued after it. For paid tools, reserving the amount blocks the call in advance, while recording afterwards only meters the spend.