ruflo-cost-tracker

Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations.

Overview

Tracks token usage per agent, task, and model, then computes USD cost attribution using current model pricing. Monitors configurable budgets with tiered alerts (info at 50%, warning at 75%, critical at 90%, hard stop at 100%). Analyzes usage patterns and recommends optimizations such as model downgrades, prompt caching, and batch operations.

Installation

claude --plugin-dir plugins/ruflo-cost-tracker

Agents

Skills

Commands (15 subcommands)

cost track                                # Auto-capture this session's token usage (producer)
cost report [--period today|week|month]   # Cost report (with By-tier block, reads measured booster data)
cost breakdown [--by agent|model|task]    # Detailed breakdown by dimension
cost optimize                             # Analyze usage and suggest savings (+ auto-emits hooks_model-outcome via outcome.mjs)
cost outcome <task> <model> <outcome>     # Emit hooks_model-outcome (success|escalated|failure) so the router learns
cost budget set <amount>                  # Set USD budget (real impl, persists to cost-tracking)
cost budget get                           # Show current budget config
cost budget check [--period ...]          # Compute utilization + alert; exit 1 on HARD_STOP
cost benchmark [--llm] [--anthropic]      # Run measured benchmark — booster + optional Gemini/Sonnet/Opus baselines
cost trend                                # Drift across bench runs (win rate, latency, regressions)
cost conversation                         # Per-conversation cost view
cost summary [--format json|markdown]     # Programmatic JSON contract for inter-plugin consumption
cost export [--prometheus] [--webhook]    # External observability — Prometheus textfile + webhook POST
cost federation                           # ADR-097 Phase 3 federation_spend consumer
cost workers                              # Inspect optimize + benchmark loop-workers consumed
cost history                              # Show cost tracking over time

Optimization integration (ADR-0002)

Four upstream capabilities are now wired to the cost-tracker surface — every optimization recommendation maps to a real tool, not a heuristic:

CLAUDE.md root percentage claims (-32% retrieval, -15% booster edits, 352x speedup, 95% cache hit) are claimed upstream, not yet verified in this repo. The skills above tag every figure with that disclaimer; only the structural $0 cost of Tier 1 bypasses is reported as a measured saving.

See ADR-0002 for the full rationale, including the riskiest assumption (no MCP wrapper for getTokenOptimizer — cost-compact-context shells a Node one-liner).

Model Pricing (per 1M tokens)

Budget Alert Thresholds

Optimization Strategies

Federation budget circuit breaker pairing (ruflo 3.6.25+)

This plugin pairs naturally with the federation budget envelope shipped in ADR-097. The federation_send MCP tool now accepts caller-supplied caps that this plugin's tracking should respect:

Phase 1 of ADR-097 enforces at the send side. Two follow-up phases will tighten the integration:

• Phase 2 (deferred) — peer state machine ACTIVE / SUSPENDED / EVICTED driven by trailing 24h cost (default suspension threshold $5) + 1h failure ratio (>50% over ≥10 sends). Auto-recovery after 30 min cooldown.
• Phase 3 (deferred) — federation_spend event bus. Each federation_send completion publishes {peerId, taskId, tokensUsed, usdSpent, ts}. This plugin's cost-tracker should aggregate per-peer rolling windows (1h / 24h / 7d) and expose them via the existing cost-report skill. Breaker queries the aggregate to evaluate suspension thresholds.

Until Phase 3 ships, federated spend is not counted in the host's cost-tracker — only local agent spend. Treat cost-report numbers as a lower bound when federation is in use.

Compatibility

• CLI: pinned to @claude-flow/cli v3.6 major+minor.
• Verification: bash plugins/ruflo-cost-tracker/scripts/smoke.sh is the contract.

Namespace coordination

This plugin owns two AgentDB namespaces:

• cost-tracking — usage records (consumed by cost-report)
• cost-patterns — optimization recommendations (consumed by cost-optimize)

Both follow the kebab-case <plugin-stem>-<intent> convention from ruflo-agentdb ADR-0001 §"Namespace convention". Both are accessed via the memory_* tool family which routes by namespace.

Routing note: The agentdb_hierarchical-* and agentdb_pattern-* tools route by tier / ReasoningBank, not by namespace string. Earlier versions of cost-report and cost-optimize passed namespace arguments to those tools and got silently-ignored behavior. ADR-0001 fixes this by switching the load path to memory_* and documenting the dual write path for optimization patterns.

Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.

Verification

bash plugins/ruflo-cost-tracker/scripts/smoke.sh
# Expected: "44 passed, 0 failed"

CI: see [`.github/workflows/cost-tracker-smoke.yml`](../../.github/workflows/cost-tracker-smoke.yml).
On every PR touching this plugin, GitHub Actions runs smoke + booster-only bench
+ regression gate (Tier 1 winRate ≥ 0.80). LLM/Anthropic baselines are NOT run in CI
— they cost real money per invocation and belong in a manual / scheduled workflow.

Architecture Decisions

• ADR-0001 — ruflo-cost-tracker plugin contract (namespace-routing fix, federation budget pairing, smoke as contract)
• ADR-0002 — agentic-flow + Agent Booster integration, model-outcome feedback loop, optimize-worker consumption, tier-aware reporting
• ADR-0003 — Implementation arc v0.5 → v0.15 (auto-capture, budget enforcement, model-outcome feedback, observability, federation consumer)

Related Plugins

• ruflo-agentdb — namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
• ruflo-observability -- Token usage metrics collected via observability instrumentation
• ruflo-neural-trader -- PnL tracking and cost-adjusted return calculation
• ruflo-federation -- Budget circuit breaker on outbound federation_send (ADR-097)

License

MIT