TokenOps skill
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.
- 84 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill edits the model call code in your project and policies can alter the agent next request
- A shared budget needs a control plane key with read and ingest scopes
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/tokenopsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill edits the model call code in your project and policies can alter the agent next request
- A shared budget needs a control plane key with read and ingest scopes
This is third-party code. Review the repository files before installing.
What it does
TokenOps sets one budget for a whole agent workflow rather than for a single request. The `integrate-tokenops` skill has your assistant wrap the model call with `wrap_complete` inside `tokenops_run`. Before each model call the run checks how much it has already spent. When the cap is reached, a `Halt` exception is raised, and sibling processes of the same run are refused. The package ships ten ready policies: cost budget, worst-case check before the call, step cap, time budget, tool output trimming and context compaction. A policy can stop the run or change the next call. A single script needs about ten lines and no server. When several processes must share one cap, you connect the separate AgentPlane control plane and keep the budget there.
Who it is for. Developers of Python multi-agent systems where one runaway loop can burn the model budget.
Good fit when
- A LangChain or hand-rolled agent calls the model dozens of times per task and you need a cost ceiling for the whole run
- Several agents in one pipeline must share a budget even when each runs as its own process
- A looping agent has to stop before the next paid call, not after the invoice
- You want to see per-agent spend on the AgentPlane dashboard
Not a fit when
- You need a gateway that routes requests between providers: TokenOps sits next to one and leaves routing to it
- You need tracing and run recording for debugging: Chronicle and observability tools do that
- The agent is not written in Python: the ready integration targets Python only
Example request
Integrate TokenOps into this agent with a two-dollar cap per run, a halt when it is spent, and a note on what to verify.Limitations
Python 3.10 or newer is required. The one mandatory change in agent code is passing `governed` in place of the model call function, so the call must be injectable. The `cost_budget` policy is a backstop and can overshoot by one call; enable `pre_call_worst_case` for a precise stop. TokenOps has no server, database or UI of its own: a shared budget across processes needs a running AgentPlane control plane and a `CONTROL_PLANE_API_KEY`. There is no local fallback ledger for a shared budget.
How to disable. Pass the original model call function back into the agent instead of `governed` and remove the `tokenops_run` call. Remove the package with `pip uninstall agent-tokenops` and delete the `integrate-tokenops` skill folder from the project `.claude/skills/`.
FAQ
How do I install TokenOps in Claude Code?
Clone the repository and run `/integrate-tokenops` in Claude Code. The skill reads the project, finds the model call and proposes the change. In Cursor and other assistants, paste the SKILL.md link and ask to integrate TokenOps.
Do I need a server?
Not for a single agent. The one-process mode works without a server or keys, and `python -m tokenops.demo` shows it on a built-in example. The AgentPlane server is needed only for a budget shared across processes.
How does TokenOps differ from an LLM gateway?
A gateway watches a request, TokenOps watches the entire run. It counts the spend of every step and tool of one workflow and works alongside a gateway.
What happens on a halt?
It raises `Halt`. You can let it propagate or catch it and return a partial result. The run is flagged halted, so later calls from other processes are refused too.
Which policies come with the package?
Policies in `docs/policies/` include cost budget, worst-case check, step cap, time budget, tool output cap, output pruning, context compaction, output runaway guard, progress guard and tool call fix. You can add your own.
Discussion
No questions or reviews yet.
Related
SkillsMicrosoft Research and UC Berkeley plugin that cuts the cost of Claude Code, Codex and Copilot CLI sessions using earlier sessions
A token-saving skill for coding agents: shorter code, tighter replies and compact handoffs between agents
Token Savior indexes code by symbol, keeps memory between sessions and rewrites noisy Bash commands so the agent spends fewer tokens
One agent launches others in the background: Claude Code, Codex, Copilot CLI, Grok Build and Pi, with a model chosen per stage.
A skill plus hooks that keep a coding agent on task and cut speculative defenses, unread checksums and scope creep
Paritok is a proxy between a coding agent and the model API that compresses requests and cuts the input-token bill.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| TokenOps (this card) | no | 84 | |
| Flightdeck | no | 264 | shows session cost and context for Claude Code on a panel but does not cap spend of an agent in your code |
| AI Observer | no | 292 | a local dashboard that observes CLI agent spend without halting a run |
README in short
The author claims up to 65 percent less wasted agent spend. The page leads from installing the skill to a ten-line manual integration, then a task table and a comparison with LLM gateways and Langfuse. A separate section splits the roles: the control plane stores settings and the shared spend ledger, Chronicle owns the trace, TokenOps makes the decisions.
README badge
Original SKILL.md
--- name: integrate-tokenops description: >- Add TokenOps run-aware token governance to a Python agent or multi-agent system: put a spend cap on a whole workflow, halt or steer a run before the next LLM call, and attribute cost per agent. Use when the user wants to cap agent spend, stop a runaway agent, budget a multi-agent run, or mentions TokenOps, tokenops_run, wrap_complete, crossing hooks, the control plane, or CONTROL_PLANE_URL. Works for a single script, a LangChain or LangGraph agent, and FastAPI / A2A multi-agent stacks. --- # Integrate TokenOps Wire a spend cap and in-path enforcement into an agent stack. Pick the smallest tier that covers the user's setup. Do not jump to Tier 3 because the project looks big. Most integrations start and stay at Tier 1. | Tier | Use when | Adds | |---|---|---| | **1. One process** | A script, notebook, or single agent | ~10 lines, no server | | **2. Shared control plane** | Several agent processes must share one budget, or you want the halt and spend visible | A running control plane and `CONTROL_PLANE_URL` | | **3. Instrumented app** | FastAPI / A2A, the trace must flow across HTTP hops | `instrument_app` + Chronicle propagation | Install: `pip install agent-tokenops` (Python 3.10+). It depends on `agent-chronicle>=1.1`. Runnable reference: `python -m tokenops.demo` (Tier 1, ships in the package). --- ## The one thing to understand first TokenOps governs a **run**, not a request. A run is one whole workflow, and it is a [Chronicle](https://github.com/theagentplane/chronicle) **trace**: the only identifier is `trace_id`. Every model call and tool call in the run shares one trace and one ledger, so a research to summarize to review pipeline stays inside a single budget even when each step is a separate process. Four moving parts: - **`tokenops_run(...)`** joins the Chronicle trace (or starts one), builds the run's attribution, loads governance, and hands back a `bound` handle. - **`wrap_complete(...)`** wraps the function that calls the model. Detect,