Offline cost and context diagnostics for AI coding agent sessions.
agent-cost-guard is a no-dependency Node.js CLI that reads local JSON/JSONL logs and reports likely cost and context issues: provider drift, prompt cache misses, repeated context, premium-model overuse, and budget overruns.
It is built for developers using Cline, OpenRouter, LiteLLM, Claude Code, Codex, or other OpenAI-compatible AI coding workflows who want a local, deterministic check before a session becomes expensive.
npm test
node ./src/cli.js demo
node ./src/cli.js report ./examples/openrouter-cline-demo.jsonl --budget 2 --out report.mdThe --budget flag exits with status 1 when the estimated session cost exceeds the threshold, so it can be used in CI.
Turns: 2
Estimated cost: $2.5000
Findings: 3
- [high] Provider drift detected: Pin the OpenRouter provider for this task or pass a stable provider.order when your agent supports it.
- [high] Cache miss spike: Keep static instructions and project context at the beginning of the prompt, reduce prefix churn, and verify provider stickiness.
- [medium] Repeated long context block: Move stable project context into a shorter brief, use cache breakpoints where supported, or split task context by phase.
The bundled fixture is synthetic demo data. It is designed to exercise the rules; it is not a provider invoice and should not be presented as real user savings.
| Check | Signal | Typical fix |
|---|---|---|
| Provider drift | Adjacent turns use the same model through different providers | Pin provider routing or preserve provider.order |
| Cache miss spike | Long prompts suddenly have little or no cached input | Stabilize prompt prefixes and provider routing |
| Repeated context | Large text blocks are resent across turns | Shorten project briefs or split context by phase |
| Model overkill | A premium model handles a small low-risk turn | Route simple planning or summarization to a cheaper model |
| Budget exceeded | Estimated session cost is above your configured budget | Fail CI, split the task, or change routing |
The CLI accepts JSON arrays, single JSON objects, JSON objects with records, generations, or data arrays, and newline-delimited JSON.
{
"model": "anthropic/claude-sonnet-4.5",
"provider": "ProviderA",
"messages": [{ "role": "system", "content": "large stable context..." }],
"usage": {
"prompt_tokens": 12000,
"completion_tokens": 320,
"prompt_tokens_details": {
"cached_tokens": 9800,
"cache_write_tokens": 0
}
},
"cost": 0.62
}See docs/log-format.md for supported aliases and examples.
OpenRouter Generation API and Activity-style records are also accepted, including fields such as provider_name, model_permaslug, tokens_prompt, tokens_completion, native_tokens_cached, total_cost, and cost_total.
AI coding agent cost is often driven by invisible session behavior:
- Long coding sessions repeatedly send the same project context.
- Prompt cache hits depend on stable prefixes and provider support.
- Provider routing can make cached input unpredictable in aggregator workflows.
- Existing observability tools are broad; this project is intentionally a small local forensic CLI.
Public signals behind the V1 scope:
- OpenRouter prompt caching docs describe provider sticky routing and cache accounting.
- OpenAI prompt caching docs document automatic caching for prompts of 1024 tokens or more and the
cached_tokensusage field. - Cline issue #10596 reports OpenRouter provider pinning problems that can inflate long-context workflow costs.
- Langfuse token and cost tracking docs, Helicone docs, and LiteLLM cost tracking docs show the broader observability category this CLI complements.
See docs/public-sources.md for the public docs and issue signals used to shape field aliases and V1 rules.
| Use case | Use agent-cost-guard |
Use observability platforms |
|---|---|---|
| Local analysis of exported AI coding logs | Yes | Sometimes |
| Deterministic rules with no hosted service | Yes | Usually no |
| Production tracing and dashboards | No | Yes |
| Team spend analytics and billing reconciliation | No | Yes |
| Quick CI budget guard from a JSONL session | Yes | Sometimes |
Provider invoices remain the source of truth. This tool estimates and diagnoses cost behavior from logs.
- More Cline, OpenRouter, and LiteLLM log fixtures.
- HTML report with simple charts.
- Provider-specific advice packs for OpenRouter, Anthropic, OpenAI, and Gemini.
- Optional config file for model tiers and team-specific budgets.
- Safer redaction helpers for sharing reports.
MIT