Know what's left. Set what's allowed. Let your agents work. Guardrails for coding agents: TokenOps watches every AI plan and account your agents draw on (Claude, Codex, Cursor, Copilot and about 90 more), steps in during the session before a limit, a budget or a rule you set is crossed, and records who let an agent go further. It runs on your machine; your prompts and your code never leave it. Free and open source; teams add shared rules and approvals.

Each vendor now shows its own windows, acts on its own harness and gives admins limits on its own seats. TokenOps holds one set of rules across all of them: headroom, budget and session-cost limits that apply to every plan and account your agents draw on, in every harness (enforced where the harness can pause a tool call, advice where it cannot). It also shows which account actually paid when a request went through a router, grades agent DX the same way across harnesses, and pauses an agent before a plan window runs out when you set a boundary on plan_left_pct. The core needs no upload at all; a team gets derived figures only, never prompts or code.

Docs: https://team.klarlabs.de/ · Releases: https://github.com/klarlabs-studio/tokenops/releases

brew trust klarlabs-studio/tap        # first time only
brew install --cask klarlabs-studio/tap/tokenops

Homebrew refuses to load a cask from a third-party tap it has not been told to trust, so the first install of anything from this tap needs brew trust klarlabs-studio/tap once — per machine, not per tool.

Or via Go:

go install go.klarlabs.de/tokenops/cmd/tokenops@latest

Or grab a prebuilt binary from the releases page (darwin amd64/arm64, linux amd64/arm64).

tokenops init                                  # writes config, registers MCP, installs hooks
tokenops plan set anthropic claude-ultra     # bind your tier (init tells you if it can't)
tokenops plan set anthropic claude-ultra --price 214.60 --currency EUR   # optional: what your bill says
tokenops daemon install                        # supervise `tokenops start` so ingestion survives reboot

init does the wiring. It finds the MCP hosts you actually have (Claude Code, Claude Desktop), registers tokenops serve with each — pinned to the absolute binary path, so a host can never silently run a stale build — installs the Claude Code hooks, and prints what still needs you:

Wiring tokenops into this machine:
  ✓ MCP: Claude Code       registered — restart Claude Code to load the tools
  ✓ Claude Code hooks      installed coach-hook + read-guard
  · plan binding           detected anthropic but not which tier you pay for

Re-run it any time to repair drift. It is idempotent, backs up every file it touches, and refuses to overwrite a host config it cannot parse. Two things stay yours: picking your plan tier (the tiers differ 4x in headroom, so guessing would make every figure confidently wrong) and pointing a client at the proxy (that reroutes your real traffic). --no-wire writes the config only. init also sets the currency totals are shown in, from your system region (--currency EUR to choose), and the coach preset (--preset observe|advise|guided|autopilot; a new config gets advise).

Then restart your MCP host and ask the agent for a compact resource view with tokenops_glance, or use tokenops_glance (view=session_budget), tokenops_spend (view=burn), and tokenops_glance (view=headroom) individually.

TokenOps surrounds the harness that owns and performs the work. It observes executions and available resources, then makes its evidence and uncertainty visible before recommending or taking an authorized action.

Observe work and resources → Understand progress and constraints
             → Compare options under policy → Recommend or act
             → Verify the result → Learn from the outcome

Recommendations and explanations are available through CLI, MCP, and the authenticated local API. Background status stays concise; evidence and history are available when requested. Autonomy is policy- and capability-specific, not a global on/off switch.

For an agent-facing before/after workflow, call tokenops_prepare_work with the task instruction and current model before starting. It returns plan headroom and a policy-based model recommendation without switching models. It also returns a stable workflow_id, the attribution header used by compatible execution paths, and a ready-to-use tokenops_review_work handoff. Preserve that identifier through execution rather than inventing another one. Afterward, call tokenops_review_work with that workflow_id to get measured token/cost totals, context growth, and any evidence-based coaching findings. The review returns aggregate metrics, not prompt content. These intent tools compose existing measurements and advice; they do not replace the harness that plans or performs the work, and preparing an identifier does not claim that execution started.

• Work and usage: Claude Code and Codex transcript ingestion, proxy-based provider metering, workflow reconstruction, cost-aware pricing, forecasts, and subscription headroom. Setup and signal coverage: tokenops status and tokenops vendor-usage status.
• Plans and money: plan switches are recorded with the date they took effect (plan set --since backdates one), so a report over a past period uses the plan in force then. Record what your bill says with --price and --currency; every total is shown in your currency, with the rate it used (the ECB's daily reference rate). See ADR 0008.
• Resource decisions: routing advice, preferred-model ceilings, plan-window constraints, approval flow, and explainable decisions. Advice is available through MCP; automatic routing requires the proxy and the configured policy and evidence gates.
• Model policy: model_policy allow and deny globs rule models out of every route — proxy routing, subagent moves, and advice — whatever the coach is set to. A company can ship it through device management; requests for a ruled-out model move to the closest-priced permitted one. See ADR 0007.
• Coach: one coach with an autonomy dial (off, advise, ask, autonomous) and a verbosity dial, over four powers: inform, waste (redundant re-reads, compacting late), models (moving subagents to a cheaper model) and context (where each agent compacts). Presets set it in one choice and wire every installed agent. It records whether its advice was followed and quiets what you ignore. See ADR 0006.
• Verification and learning: record human or verifier outcomes, explain past decisions, run bounded local routing experiments, and compare results against baselines. Learning is advisory and gated; it does not rewrite runtime behavior on its own.
• Workflow coaching: prompt and reply coaching, Agent-DX metrics, scorecards, task-level cost and rework, and context/compaction signals derived from supported harnesses.
• Execution support: deterministic tokenops fmt -- <cmd> compression preserves critical output and keeps full output recoverable locally. Hooks and integrations act only where the client supports the required authority.
• Local-first surfaces: Go daemon, SQLite event store, MCP server, protected local API, and CLI. No cloud account or telemetry is required; the core product is Apache 2.0. It makes two outbound calls of its own, both downloads that send nothing about you: a daily public rate card (LiteLLM and models.dev), and the ECB's daily exchange rate when your currency is not the US dollar. Each is one line to switch off (pricing.refresh.disabled, money.fetch_rate).

See docs/architecture-ddd.md for bounded contexts and layer rules; docs/plan-cost-model.md for the subscription-plan model; and the integration capability matrix for source coverage and client-specific limitations.

tokenops on its own shows every plan as a card, with the coach's findings underneath. tokenops --help groups the rest:

Every day
  glance                    every plan's windows, pace, cost and the coach's findings
  spend [--forecast]        what you spent, where it went, where it is heading
  spend --by commit         what each of your commits cost
  story                     what you asked for, what the agent did, where it went sideways
  dx [--fresh]              how sessions go: turns, rework, interrupts, the one change to make
  status                    whether TokenOps is working, and what to fix
  explain [term | decision] what a figure means, or why TokenOps decided what it did

Set up
  init                      set up this machine: plans, client hooks, the daemon
  detect                    which AI clients are installed (changes nothing)
  daemon {install|restart|status|uninstall}
  hooks {install|status|uninstall}
  statusline {install|uninstall|subagents}
  menubar                   install and open the menu bar app (macOS)
  plan {set|list|headroom|history|catalog|unset}
  budget {list|set|unset}
  provider {list|set|unset}
  vendor-usage {status|enable|setup|backfill}
  pricing {show|refresh|diff|lint}
  otel                      what the daemon pushes to an OpenTelemetry collector
  config show

Coach, routing and policy
  coach [preset|autonomy|verbosity|set|off|stats|prompts|replies]
  mode [passive|active]
  routing {proposals|rule}
  preferred-model {list|set|unset}
  experiment {start|status|stop}
  rules {analyze|conflicts|compress|inject|bench}
  fmt -- <cmd>              compress a command's output before the agent reads it
  task {start|done|list}
  outcome {record|detect|check-json}

Look closer
  scorecard · optimizations · verify · audit · events

The hooks your clients call (coach-hook, read-guard, route-guard), the MCP server (serve), the daemon's foreground process (start) and the tools for working on TokenOps itself (eval, coverage-debt, replay) run as before but stay out of the help.

Most CLI verbs have a matching MCP tool (tokenops_<name>). fmt is CLI-first (it wraps a shell command); its learning report is exposed to agents via tokenops_fmt (view=learn).

Default install reports low confidence (MCP pings only). Two zero-network upgrades:

# ~/.config/tokenops/config.yaml
vendor_usage:
  claude_code:
    enabled: true              # reads ~/.claude/stats-cache.json
    interval: 60s
  anthropic:
    enabled: true              # calls Anthropic Admin API
    admin_key: sk-ant-admin-…  # mint in claude.com console
    interval: 5m

tokenops vendor-usage status shows whether the pollers are emitting; use tokenops vendor-usage backfill --hours 168 to pull a week of history from Anthropic Admin in one shot after configuring the key.

The Anthropic Admin API only covers metered API usage. Claude Max plan window state has no documented endpoint and stays heuristic — the cache reader is the only locally-available Max signal and reports daily granularity with an explicit caveat.

Clients / SDKs / CLIs / MCP hosts
            |
            v
   Local TokenOps daemon (Go)
      /     |       \
 Proxy    MCP      HTTP API
   |     server     /api/*
   v        |        |
 Provider routes    CLI / integrations
 (OpenAI/Anth/Gem/Mistral)
            |
            v
    SQLite event store
            |
            v
 Decisions → outcomes → evidence tiers
            |
            v
 Spend / forecast / coaching / learning

DDD-organised: contexts under internal/contexts/<ctx>/<pkg>, adapters (cli, mcp, proxy) stay flat. Layering enforced by internal/archlint (go test ./internal/archlint/...).

cmd/{tokenops,tokenopsd}/         # binaries
internal/
  contexts/                       # bounded contexts (rules, spend, security, ...)
  cli/                            # cobra subcommands
  mcp/                            # MCP tool surface
  proxy/                          # HTTP API server
  daemon/                         # boot sequence
  storage/sqlite/                 # event store
pkg/eventschema/                  # public envelope + payload types
docs/reference/                  # CLI, configuration and API reference
.roady/                           # spec-driven planning

TokenOps instruments AI usage on three planes; which ones a client supports is the whole integration story. Full matrix + provider list: docs/integrations/coverage.

• Passive read — reads logs the client already writes; per-turn attribution (turn → session → project), zero wiring.
• MCP (tokenops serve) — the agent calls TokenOps; tokenops_status reports what's live and the exact command to upgrade signal quality.
• Proxy — point the client's base URL at TokenOps for ground-truth token/cost accounting. OpenRouter (tokenops provider set openrouter) is the universal fallback for any client with no local reader.

Honest boundaries: Gemini CLI has no local token log (proxy only); AWS Bedrock needs SigV4 the passthrough proxy can't do; fully-hosted agents (Jules) are out of reach — TokenOps is local-first with no telemetry.

Parity across clients does not exist, and the matrix says so. Desktop and GitHub clients have no local token log and no base-URL override, so coaching there is pull-only: no transcripts means no storytelling, no proactive nudges, no routing. What is left is the MCP surface, which on those clients is the whole product. The capability matrix lists what reaches which client, feature by feature, gaps included.

When a subsystem is off, the matching routes return 503 with a structured {error, hint} body instead of 404. tokenops status (and the MCP tokenops_status tool, and GET /readyz) surface stable identifiers in blockers[] plus the exact command in next_actions[]:

MCP activity pings are excluded from default rollups because they are not provider requests:

Re-admit MCP activity pings with --include-source (CLI) or include_sources (MCP tool input) when you explicitly need them:

tokenops spend --include-source=mcp-session

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md. Plans and tasks live in .roady/ (see roady).

See CHANGELOG.md — latest is v0.71.0.

Apache License 2.0. See LICENSE.