convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
felixgeelhaar

TokenOps

felixgeelhaar/tokenops

Previne esgotamento de cota de IA com alertas em tempo real

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server e CLI que monitora janelas de taxa-limite em planos de IA (Claude Max, ChatGPT Plus/Pro/Team, GitHub Copilot, Cursor, Mistral). Prediz quando você vai atingir o cap e avisa seu agente para desacelerar, trocar modelo ou aguardar reset.

Instalação

$npx convez-ai felixgeelhaar/tokenops

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v0.122.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar consumo de tokens em agentes Claude em produção
  • Gerenciar múltiplas contas e planos de IA simultaneamente
  • Tomar decisões dinâmicas de modelo baseado em headroom restante
  • Rastrear custo real de cache hits em workloads de agentes

Veredito

Ferramenta especializada e bem-engineered para quem roda agentes Claude em escala e precisa controlar custos. Preenchimento claro de gap que não existe em SDKs nativos, mas requer integração MCP deliberada no seu setup.

README

A tradução para o português deste README ainda está na fila.

TokenOps

CI Release License Go Report

Predict rate-limit cutoffs inside your AI agent. Local MCP server + CLI that watches your flat-rate AI subscription window — Claude Max, ChatGPT Plus / Pro / Team, GitHub Copilot, Cursor, Mistral Le Chat Pro, Codex Plus — and tells the agent, before you hit the cap, to continue, slow_down, switch_model, or wait_for_reset.

Docs: https://felixgeelhaar.github.io/tokenops/ · Releases: https://github.com/felixgeelhaar/tokenops/releases

Install

brew install felixgeelhaar/tap/tokenops

Or via Go:

go install github.com/felixgeelhaar/tokenops/cmd/tokenops@latest

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

90-second quickstart

tokenops init --detect                         # sniff installed AI clients, print plan-set commands
tokenops plan set anthropic claude-max-20x     # bind whatever fits (paste from --detect output)
tokenops start                                 # daemon, listens 127.0.0.1:7878 + tokenops.local

Wire MCP into your agent:

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

Ask the agent for any of: tokenops_session_budget, tokenops_burn_rate, tokenops_dashboard, tokenops_plan_headroom. Or open the browser dashboard the agent links you to (http://tokenops.local:7878/dashboard?token=…).

Features

🧮 13 plan catalogClaude Max 5x/20x, Claude Pro, Claude Code (Max + Pro), ChatGPT Plus / Pro / Team, GitHub Copilot Individual / Business, Cursor Pro / Business, Mistral Le Chat Pro, Codex Plus — each with a dated vendor source URL pinned in code
🔌 Provider-agnosticOpenAI, Anthropic, Google Gemini, Mistral through the same proxy and event schema
📊 Interactive dashboardVue 3 + D3 dashboard at /dashboard — cost line, per-model stacked area, tokens-per-bucket, KPI tiles, 15s auto-refresh, provider + model filters that persist across refresh
📍 mDNS-discoverableDaemon advertises tokenops.local over zeroconf so the dashboard URL is memorable on every host
🔐 Dashboard authShared-secret token, auto-minted on first start, accepted via header / query / cookie. tokenops dashboard rotate-token revokes
📡 Vendor /usage ingestionLive per-turn JSONL readers for Claude Code (~/.claude/projects/) and Codex CLI (~/.codex/sessions/), plus GitHub Copilot OAuth quota, Cursor cookie scrape, Anthropic cookie scraper (only source of the official Claude Max weekly %). Each source has a tokenops vendor-usage enable <source> wizard with env-var fallback for secrets
💰 Cache-aware pricingClaude + Codex cache reads bill at ~10% of the new-input rate. For agent-heavy workloads cache reads are >95% of input — the dashboard Cache hit: XX.X% tile + cost-aware aggregator make the difference between a naive $94k estimate and the real $10k. Per-provider rate cards ship in code
🧪 Per-project / per-session attributionJSONL pollers stamp agent_id = "claude-code:<project>" and workflow_id = "claude-code:<project>:<session>" (analogous for Codex). group=agent answers "which project burns the most"; coach finds per-session waste
🧠 Prompt coachtokenops coach prompts heuristic feedback on your real prompting patterns — length distribution, vague/ack/repeat detection, concrete recommendations. Auto-discovers Claude Code + Codex JSONLs. Prompt text never persisted. Ranked recommendations (v0.18) project tangible savings: turns × tokens × dollars × hours per win
📋 Reply coachtokenops coach replies detects output-compression patterns (caveman skill, article density, filler density) per session
⏱️ Task boundariestokenops task start "fix X" / done / list --metrics — operator-marked task units persisted to ~/.tokenops/tasks.jsonl. List view rolls up turns / cost / TTFUO / cost-per-turn from the events store within each task window
📐 8-KPI agent scorecardFVT / TEU / SAC (wedge) plus CHR / CGR / RGR / TCS / DAR (agent-workflow), all graded A–F against tuneable thresholds. v0.21.1 honest grading: TEU N/A when optimiser isn't wired; autonomous-loop sentinels filtered from CGR; column→payload attribution sync so SAC reflects reality
🎯 Honest signal qualityEvery prediction carries signal_quality.level (low / medium / high) plus a one-line caveat. Heuristic mode is labelled; proxied mode is labelled
🤖 MCP-first25 MCP tools agents call directly. Inline SVG sparkline + headroom gauge rendered in markdown so every MCP client shows them today
🧠 Dynamic-cheapest coachingCoaching pipeline picks the lowest blended-rate model per provider at runtime from the pricing table — no hardcoded model names
💾 Local-first, open sourceSQLite database, no cloud account, no telemetry. Apache 2.0. Demo-data isolation by default so synthetic seeds never contaminate the real signal

See docs/architecture-ddd.md for the bounded contexts and layer rules; docs/plan-cost-model.md for the plan catalog model.

CLI surface

init                              Scaffold config (sqlite + rules on); --detect sniffs installed clients
start                             Run the daemon (proxy + analytics + bus + dashboard)
serve                             MCP server over stdio
demo                              Seed 7d of synthetic events
status                            Daemon health + blockers[] / next_actions[]
spend [--forecast]                Spend / burn / 7d forecast
plan {list|set|headroom|catalog}  Subscription plan headroom
provider {list|set|unset}         Upstream LLM provider URLs
vendor-usage {status|backfill}    Inspect / backfill vendor-side pollers
dashboard rotate-token            Mint + persist a fresh dashboard auth token
config show                       Active configuration (redacted)
audit                             Query audit log
events                            Per-kind domain-event counts
rules {analyze|conflicts|...}     Rule intelligence
scorecard                         Wedge KPI scorecard
coverage-debt                     Risk-weighted coverage debt
eval                              Optimizer eval harness + gate
replay <id>                       Replay a session through the optimizer

Every CLI verb has a matching MCP tool (tokenops_<name>).

Upgrading signal quality

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.

Architecture

Clients / SDKs / CLIs / MCP hosts
            |
            v
   Local TokenOps daemon (Go)
      /     |       \
 Proxy    MCP      Dashboard
   |     server     /api/*
   v        |        |
 Provider routes     Vue+D3
 (OpenAI/Anth/Gem/Mistral)
            |
            v
    SQLite event store
            |
            v
 Spend / forecast / coaching

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 server + dashboard
  daemon/                         # boot sequence
  storage/sqlite/                 # event store
pkg/eventschema/                  # public envelope + payload types
web/docs/                         # VitePress docs site
.roady/                           # spec-driven planning

Disabled-subsystem contract

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[]:

BlockerFix
storage_disabledtokenops init then restart
rules_disabledtokenops init then restart
providers_unconfiguredtokenops provider set …

Demo data isolation

tokenops demo writes synthetic PromptEvents tagged source=demo. Every default rollup filters them out so first-run exploration never contaminates production numbers. Pass --include-demo (CLI) or include_demo: true (MCP tool input) to see the synthetic breakdown alongside real traffic.

Contributing

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

Changelog

See CHANGELOG.md — latest is v0.21.1.

License

Apache License 2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados