Quickstart

Ninety seconds from zero to "my agent knows my rate-limit window."

1. Install

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 GitHub Releases.

2. Initialise with auto-detection

tokenops init --detect

--detect sniffs Claude Code, Claude Desktop, Cursor, ChatGPT Desktop, and ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY. The output ends with a paste-ready list of tokenops plan set … commands for everything it found. Pick the ones that fit your plan tiers:

tokenops plan set anthropic claude-max-20x
tokenops plan set openai gpt-plus

3. Start the daemon

tokenops start

Foreground. For a machine that reboots, supervise it so ingestion survives (the 27-day outage class):

tokenops daemon install

The daemon binds 127.0.0.1:7878, opens the SQLite store, mounts its authenticated /api/* endpoints, publishes itself as tokenops.local over mDNS, and writes its listen URL + API token to ~/.tokenops/daemon.url (0600) for local clients.

The API answers the same questions the MCP tools do, from the same code (ADR 0010), so a menu bar or a script never opens the store itself. GET /api/glance is the one-call view: session budgets, plan headroom with every window the vendor reports, and a ranked insight. GET /api/plans/headroom and GET /api/plans/session-budget return the two halves. Every route is listed in Daemon API.

4. Wire the MCP server into your agent

{
  "mcpServers": {
    "tokenops": {
      "command": "tokenops",
      "args": ["serve"]
    }
  }
}

Then ask your agent for any of these:

tokenops_glance (view=session_budget)        # headroom gauge + recommended action
tokenops_spend (view=burn)             # 24h sparkline + cost total
tokenops_glance (view=headroom)         # month-to-date headroom per plan

(Optional) Upgrade signal quality

Default install reports low confidence (MCP pings only). Two zero-network-config 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

Claude Code stats cache promotes Anthropic confidence to medium (daily granularity, undocumented schema — caveat in every response). Anthropic Admin API promotes it to high for metered API usage (Claude Max plan window state is not exposed by any documented endpoint and stays heuristic).

(Optional) Route SDK calls through the local proxy

Higher-quality signal: TokenOps observes every request instead of just MCP tool invocations.

export OPENAI_BASE_URL="http://127.0.0.1:7878/openai/v1"
export ANTHROPIC_BASE_URL="http://127.0.0.1:7878/anthropic"

Gemini: pass httpOptions.baseUrl = "http://127.0.0.1:7878/gemini" to genai.Client(). For richer attribution, set workflow / agent IDs as headers:

X-Tokenops-Workflow-Id: research-summariser
X-Tokenops-Agent-Id: planner

CLI quick reference

tokenops spend --forecast           # spend + 24h burn + 7d forecast
tokenops scorecard                  # operator wedge KPIs
tokenops plan list                  # configured plans + headroom
tokenops vendor-usage status        # show poller state + event counts
tokenops vendor-usage backfill --hours 168   # one-shot Anthropic Admin pull

See the CLI reference for the full surface.

Next steps

• SDK shim reference — Python + Node + curl
• CLI reference
• Architecture — how the pieces fit