Wrap your model call once, then hand the wrapped version to your agent. Needs CONTROL_PLANE_URL (or TOKENOPS_URL) pointing at a running control plane — see Quickdeploy.

from tokenops import ControlPlaneClient, tokenops_run
from tokenops.control import Halt, wrap_complete
from tokenops.providers import complete

client = ControlPlaneClient.from_env()  # raises if CONTROL_PLANE_URL isn't set

with tokenops_run(client=client, service="my-agent", intent="research",
                  provider="openai", model="gpt-4o") as bound:
    governed = wrap_complete(
        bound.governor, bound.controls, bound.attr,
        provider="openai", model="gpt-4o",
        dispatch=complete, service="my-agent",
    )
    try:
        agent.run(..., complete_fn=governed)   # <-- pass `governed`, not `complete`
    except Halt as stopped:
        print(f"run stopped: {stopped}")

Pass governed to your agent instead of complete; nothing else changes. wrap_complete checks the budget before each call and raises Halt when the run is out, even from another process.

git clone https://github.com/theagentplane/tokenops && cd tokenops
make install
make run          # control plane :7700 + Admin/Dashboard :8501

Then open localhost:8501 to see spend and governance per agent.

Each is a real multi-agent stack sharing one run ledger. One target starts the plane, the agents, and the Admin UI.

cp .env.example .env first if you want them to call real models. See examples/README.md for the bench profiles.

export TOKENOPS_URL=http://localhost:7700
export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file

tokenops has no ledger of its own — every process governs against the plane at TOKENOPS_URL. There is no local-fallback env var to accidentally leave unset.

PyPI name is agent-tokenops; the import is tokenops. Extras: pip install "agent-tokenops[examples]" for the LangChain benches, ".[dev,examples]" from source. Releases: RELEASING.md.

TokenOps is two layers that share one artifact, the run: a control plane that registers runs and stores budgets/policies, and an in-process SDK that enforces at every boundary crossing.

flowchart LR
    subgraph PLANE["Control plane (:7700)"]
        R["POST /v1/runs"] --> DB[("SQLite TOKENOPS_DB<br/>registrations · budgets · policies · ledger")]
        UI["Admin + Dashboard"] --> DB
    end

    subgraph AGENTS["Agent processes (SDK)"]
        E["Entry agent<br/>tokenops_run"] -->|"register_run"| R
        E -->|"X-TokenOps-Run-Id"| D["Downstream agents<br/>tokenops_run"]
        E & D -->|"wrap_complete"| G["Governor<br/>pre_call → detect → decide → apply"]
        E & D -->|"@boundary + crossing hook"| G
        G --> L["Shared ledger<br/>(same run_id)"]
    end

    L --> DB
    DB -->|"governance_config_for"| G

Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See Chronicle for record-and-replay, accepted at REALM (Research on Agent Language Models), a workshop at EMNLP 2026.

tokenops has no ledger or run registry of its own — ControlPlaneClient.from_env() raises if TOKENOPS_URL/CONTROL_PLANE_URL isn't set, rather than silently falling back to anything local. Every process talks to the same plane, so they share one budget by construction. TOKENOPS_URL also accepts the alias TOKENOPS_CONTROL_PLANE_URL.

Only src/tokenops/ is the installable package. Demos and benches stay under examples/.

src/tokenops/              # installable package
├── server/                # control plane (:7700, POST /v1/runs)
├── control/               # SDK: ledger, policies, wrap_complete, crossing hook
├── providers/             # OpenAI / Anthropic complete dispatch
├── config/                # default.yaml governance seed
└── ui/                    # Admin + Dashboard (Streamlit)
examples/                  # A2A benches (two-agent, triad, brief) + Chat/Simulator
benchmarking/              # MetaGPT / browser-use live harness
docs/                      # architecture, policies, guides, product
tests/                     # unit + e2e

• Onboarding: prereqs, minimum integration, FAQ, current limits
• Field guide: a triad walked through, with screenshots
• Policies: one page per policy
• Run attribution - control plane deploy - status
• Examples - comparison - shared ledger