Local MCP server + CLI for flat-rate AI subscriptions (Claude Max, ChatGPT Plus / Pro / Team, GitHub Copilot, Cursor, Mistral Le Chat Pro, Codex Plus). Your agent asks `tokenops_session_budget` mid-task and gets back a headroom gauge plus one of four recommended actions — instead of you tab-flipping to a vendor `/status` page.
/status and a billing tab Today, when your agent is mid-refactor and Claude returns "limit reached, resets in 4h," your options are: open the Anthropic console in another tab, paste /status into your terminal, refresh the billing page, or just eat the wait. None of those tell the agent anything.
TokenOps puts the headroom check inside the agent's loop. The agent calls one MCP tool, sees 62% headroom, 1h41m to reset, recommended_action: continue (or slow_down, switch_model, wait_for_reset), and proceeds without you alt-tabbing.
The MCP surface is a deterministic guardrail, not vibes-in-the-loop. Closed action enum, calibrated confidence:
{
"tool": "tokenops_session_budget",
"response": {
"headroom_pct": 62,
"window_resets_in": "1h41m",
"recommended_action": "continue",
"signal_quality": {
"level": "high",
"source": "vendor_usage_api",
"caveat": null
}
}
}recommended_action is a closed enum (continue | slow_down | switch_model | wait_for_reset) so the agent picks the right branch without parsing prose. signal_quality.level lets the agent decide how much to trust the call: stay aggressive on high, defer to the human on low.
continue ×100+ from /loop mode isn't a human ack). Overall grade F → B on real 30d data.tokenops task start|done|list (v0.20–v0.21). Operator-marked task boundaries persist to ~/.tokenops/tasks.jsonl. task list --metrics enriches every task with the events-store rollup: turns, input/output tokens, cache-aware cost, TTFUO, cost-per-turn.tokenops coach prompts ranked recommendations (v0.18) project tangible savings (tokens / dollars / hours) per win, grounded in the operator's own turn averages. JSON output ships { findings, turn_stats } for MCP-host UIs.tokenops coach replies detects output-compression patterns (caveman-skill verdict, article density, filler density). Anthropic admin-API events now stamp synthetic agent_id / workflow_id so they don't drag SAC down.claudecodejsonl poller stamps agent_id = "claude-code:<project>" and workflow_id = "claude-code:<project>:<session>". group=agent answers "which project burns the most"./api/spend/cache_stats. The dashboard Cache hit: XX.X% tile; for agent workloads the ratio routinely sits >95%.claude-code: and codex: workflows (900k / 250k peak respectively) — stops short-workflow defaults firing on every session.SessionID, AgentID="codex", WorkflowID="codex:<session>", and CachedInputTokens on every PromptEvent.tokenops coach prompts auto-discovers Codex. Scans both ~/.claude/projects AND ~/.codex/sessions.tokenops coach prompts (v0.15.0). Heuristic prompt-quality feedback for Claude Code users. Walks ~/.claude/projects/**/*.jsonl, extracts human-typed turns, reports length distribution, vague/ack/repeat counts, and concrete recommendations. Prompt text is read at scan time and is never persisted to the event store. MCP tool tokenops_coach_prompts exposes the same surface to agent hosts.session_id + workflow_id on the indexed columns (not just attributes), so tokenops replay + the waste detector resolve Claude Code sessions. Coach surface was dark for JSONL data; now it surfaces oversized-context + runaway-growth findings per session.json_extract. On real 7-day data: $94k → $10k.Summarize cost recompute (v0.14.1). Dashboard TOTAL COST showed $0.00 for any data from vendor-usage-jsonl sources (those readers ship token counts but no prices). Fixed by recomputing via spend.Engine in the same path AggregateBy already used.tokenops vendor-usage enable <source> (v0.14.0). Writes a vendor-usage source's config block so operators don't hand-edit YAML to flip the v0.13.0 pollers on. Six sources: anthropic-cookie, cursor, github-copilot, codex-jsonl, claude-code-jsonl, anthropic-admin. Secrets accept env-var fallback (TOKENOPS_ANTHROPIC_COOKIE_SESSION_KEY, etc.).~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl, surfaces OpenAI's authoritative rate_limits block (5h primary + weekly secondary used_percent + resets_at).api.github.com/copilot_internal/user with the OAuth token Copilot IDE plugins already manage. Auto-discovers from ~/.config/github-copilot./api/usage poller — cookie-based scrape of cursor.com.claude.ai/api/organizations/{org_id}/usage with the operator's browser sessionKey. The only source that surfaces the official Claude Max weekly utilization %.~/.claude/projects/<project>/<session>.jsonl — Claude Code's live per-turn conversation record — and emits one PromptEvent per assistant turn with the full message.usage block. The v0.10.2 stats-cache reader was lagging by days; deprecated in favour of this.tokenops.local via mDNS (v0.10.1) — The daemon advertises itself over zeroconf on Start, so the dashboard URL becomes http://tokenops.local:7878/dashboard instead of a bare loopback address. The tokenops_dashboard MCP tool prefers it; falls back to 127.0.0.1 when .local resolution isn't available.~/.claude/stats-cache.json and emits per-(date, model) deltas (signal_quality → medium). The Anthropic Admin API poller calls /v1/organizations/usage_report/messages every 5min with an admin key (signal_quality → high). Both wired through config.vendor_usage.*; both honest about the Claude Max 5h-window blind spot./dashboard + /api/* now require a shared-secret token (/healthz, /readyz, /version stay public). Daemon mints + persists the token automatically at ~/.tokenops/dashboard.token; the MCP tool returns a clickable URL with the token pre-attached so the operator gets a one-click authenticated visit. Browser-style auth mints a session cookie and 303s to a clean URL so the token never lingers in history.tokenops init --detect reads your installed AI clients (Claude Code/Desktop, Cursor, ChatGPT Desktop, env-var API keys) and prints the exact plan-set commands. Run it once, paste what fits./dashboard. Hourly cost line, tokens-per-bucket stacked bar, KPI tiles, 15s auto-refresh. Driven by the same /api/spend/* endpoints the CLI uses.tokenops_session_budget leads with a coloured headroom gauge (green / amber / red by overage band); tokenops_burn_rate ships a sparkline. Rendered inline in markdown so every MCP client shows them today.Every major vendor — Anthropic, OpenAI, GitHub, Cursor, Google — publishes rate-limit windows, not monthly token caps, for their flat-rate plans. The vendor dashboard tells you you've hit the cap after the cap hits. There's no early signal in the agent context where you're actually working.
TokenOps closes that gap for every provider it tracks. One CLI, one MCP server, one event schema. Configure as many plans as you use:
tokenops plan set anthropic claude-max-20x
tokenops plan set openai gpt-plus
tokenops plan set github copilot-business
tokenops plan set cursor cursor-proEvery plan you bind contributes to a unified headroom view your agent can query mid-conversation.
TokenOps reports its own signal quality on every prediction. Four sources, ranked by faithfulness:
mcp_tool_pings (low) — Default. Counts MCP invocations as an activity proxy. Useful as a "is the agent talking to me?" signal, not a quota meter.claude_code_stats_cache (medium) — Daemon reads ~/.claude/stats-cache.json on a tick (config: vendor_usage.claude_code.enabled: true). Per-model daily totals; can't resolve the 5h rolling window but gives real attribution. Schema is undocumented — every response carries a caveat.proxy_traffic (high) — Wire your SDK's base URL through the local proxy (OPENAI_BASE_URL, ANTHROPIC_BASE_URL, GEMINI_BASE_URL). Captures every request per-event.vendor_usage_api (high) — Anthropic Admin API poller (config: vendor_usage.anthropic.{enabled, admin_key}) reads /v1/organizations/usage_report/messages directly from Anthropic. Covers metered API usage only; Claude Max plan window state has no documented endpoint and stays heuristic.If you don't recognise the struggling moment, this isn't the product for you yet.
If you'd trade a 15-minute call for hands-on help wiring TokenOps to your workflow, open an issue on GitHub or DM @felixgeelhaar. Current focus is the first ten real users — across any provider mix.