token-usage
/token-usage
Nested swiss-knife reference for token usage, cost, cache, and tool-call/API-call reports. Use for model cost reports, cache rates, budget/burn analysis, and tools-per-API-call trends across LingTai logs.
- Author
- lingtai-ai ↗
- Repository
- lingtai ↗
- Licence
- Apache-2.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/cost_report.py, scripts/tool_calls_per_api_call_trend.py
What it does and when to use it
Nested swiss-knife reference for token usage, cost, cache, and tool-call/API-call reports. Use for model cost reports, cache rates, budget/burn analysis, and tools-per-API-call trends across LingTai logs.
Original author description
Nested swiss-knife reference for token usage, cost, cache, and tool-call/API-call reports. Use for model cost reports, cache rates, budget/burn analysis, and tools-per-API-call trends across LingTai logs.
How it works
- Quick Usage
- How It Works
- Pricing Sources
- Custom Pricing Format
- Ledger Format
- Dependencies
- Tips
SKILL.md preview
---
name: token-usage
description: >
Nested swiss-knife reference for token usage, cost, cache, and tool-call/API-call reports.
Use for model cost reports, cache rates, budget/burn analysis, and tools-per-API-call trends across LingTai logs.
version: 2.1.0
tags: [python, cost, tokens, litellm, budget, tools, agents]
last_changed_at: "2026-07-18T00:00:00Z"
maintenance: "If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths."
---
# Token Usage, Cost, and Agentic-Intensity Reports v2
Network-wide token cost analysis powered by [litellm](https://github.com/BerriAI/litellm)'s model pricing database (2700+ models), plus runtime-event trend analysis for tool calls per API call.
## Quick Usage
Run the bundled cost script:
```bash
~/.lingtai-tui/runtime/venv/bin/python3 ~/.lingtai-tui/utilities/swiss-knife/reference/token-usage/scripts/cost_report.py /path/to/.lingtai
```
Cost-report optional flags:
- `--json` — output as JSON instead of table
- `--by-model` — group by model instead of by agent
- `--since YYYY-MM-DD` — only count entries after this date
- `--top N` — show only top N agents (default: all)
- `--custom-pricing FILE` — load custom pricing overrides from JSON
### Tool-call/API-call trend
Use this when the human asks for “tool calls per API call”, “tools per API call”, “agentic intensity”, or how tool-heavy the local LingTai network has been over time. The script reads LingTai `logs/events.jsonl` files, not `token_ledger.jsonl`, because it needs runtime event IDs.
```bash
~/.lingtai-tui/runtime/venv/bin/python3 ~/.lingtai-tui/utilities/swiss-knife/reference/token-usage/scripts/tool_calls_per_api_call_trend.py \
/path/to/project/.lingtai \
--days 5 \
--timezone America/Los_Angeles \
--model gpt-5.5
```
Optional flags:
- `--out-prefix PREFIX` — write `PREFIX.md`, `PREFIX.json`, and `PREFIX.csv`
- `--model MODEL` — also emit a model-specific table for an exact model name; repeatable
- `--include-daemons` — include daemon event logs instead of excluding them
Metric definitions:
- **API calls:** unique successful LLM response events (`type == "llm_response"`), deduplicated by `(events log path, api_call_id)`.
- **Tool calls:** unique model-requested top-level tool calls (`type == "tool_call_received"`), deduplicated by `(events log path, api_call_id, tool_call_id)` and assigned to the local-day bin of the producing API response.
- **Tool calls per API call:** `tool_calls / api_calls`.
- **Tool-using API-call rate:** fraction of API calls that produced at least one tool call.
Treat the metric as behavioral intensity, not token volume: a higher value means each model API call is asking the runtime to do more tool work on average.
## How It Works
`cost_report.py` scans every `logs/token_ledger.jsonl` under `.lingtai/`, prices
each entry via litellm `model_cost` → OpenRouter → custom-pricing fallback (see
below), and reports per-agent/grand-total cost plus cache-hit and burn rates.
`tool_calls_per_api_call_trend.py` instead scans `logs/events.jsonl`, counts
`llm_response` / `tool_call_received` events, and writes Markdown/JSON/CSV daily
trend artifacts.
## Pricing Sources
**Primary:** litellm's `model_cost` dictionary — covers OpenAI, Anthropic, Google, Meta, Mistral, Xiaomi, and 100+ other providers.
**Secondary:** OpenRouter API — real-time pricing for 368 models, more up-to-date than litellm for some providers.
**Fallback:** Custom pricing in `scripts/custom_pricing.json` — for models not yet in litellm or OpenRouter (e.g., MiMo v2.5 Pro direct API).
**Override:** Pass `--custom-pricing FILE` to add project-specific pricing.
## Custom Pricing Format
```json
{
"mimo-v2.5-pro": {
"input_cost_per_token": 0.000001,
"output_cost_per_token": 0.000003,
"cache_read_input_token_cost": 0.0000002
}
}
```
## Ledger Format
Each agent's `logs/token_ledger.jsonl` has one JSON object per LLM call:
```json
{
"source": "main",
"ts": "2026-05-06T19:31:40Z",
"input": 53295,
"output": 277,
"thinking": 172,
"cached": 12288,
"model": "mimo-v2.5-pro",
"endpoint": "https://api.xiaomimimo.com/v1"
}
```
## Dependencies
- `cost_report.py` requires `litellm`. Check with `python3 -c "import litellm"`. If missing, ask the human before installing:
> token-usage needs `litellm` (~5MB) for model pricing. Install it? (`pip install litellm`)
Install only after they say yes.
- `tool_calls_per_api_call_trend.py` uses only the Python standard library.
- Python 3.9+
## Tips
- Check after spawning multiple avatars — they each burn their own system prompt
- Cache hit rate is the key efficiency metric — aim for >90%
- Tool calls per API call is a useful agentic-intensity metric: values above 1 mean the average model response asks for more than one tool call
- Daemon tokens are tracked in `daemons/<run_id>/logs/token_ledger.jsonl`
- For per-session breakdown, use `--since` to filter by date
---
> **Found a bug or issue?** If you encounter any problems with this skill, load the `lingtai-issue-report` skill and follow its instructions to report it.
Files in this package (4)
- SKILL.md 5 KB
- scripts/cost_report.py 14 KB
- scripts/custom_pricing.json 1 KB
- scripts/tool_calls_per_api_call_trend.py 17 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · lingtai-ai/lingtai | 100 | Apache-2.0 |
| orenlion1/investigation-skills | 100 | MIT |
| iress/design-system | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 1b11137ad672 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100token-cost-analyzer
Use this skill when analyzing and optimizing LLM API costs. Activate when the user wants to reduce AI API spending, understand token usage, audit LLM costs, optimize prompts for cost efficiency, or track and report on AI expenditure. - 100tokenmeter
Open the Tokenmeter dashboard, a local web page that tracks token usage, cost, rate-limit windows and cache misses for every prompt in Claude Code, Codex and Copilot CLI. Use when the user asks about token usage, token spend, cost per prompt or per commit, cache hit rate, usage… - 100claude-token-spend
Report Claude Code token consumption from local session logs - per model, per project, and per token type (input, output, cache read, cache write) over 24h / 7d / 30d / all-time windows. Reads ~/.claude/projects directly, no API key, read-only. Triggers on "my token spend",… - 90context-optimization
Use when optimizing token usage, KV cache efficiency, or context window management for LLM agents. Keywords: context optimization, KV cache, prompt caching, token budget, semantic pruning, lost-in-the-middle. - 100cv-usage
Use when the user asks about usage analytics, statistics, token usage, or cost summary — e.g. 'usage stats', 'token usage', 'how many sessions this week', 'show me my numbers', 'cost summary', 'usage report - 90session-budget
Use when tracking token/cost budget per session — monitors API usage and compute costs