Nanobot
Nanobot makes token usage a structured runtime record
Nanobot proposes structured token records and per-iteration diagnostics after an operator reported unexplained token burn. The new records separate model, provider, input, output, cache and reasoning counts so usage can be inspected without scraping prose logs.
HKUDS/nanobot PR #5299 is the inspected primary source: “feat(api): expose structured token usage records.” The related records below were inspected as supporting context rather than independent confirmation.
The facts
- HKUDS/nanobot PR #5299 was created 2026-08-08T13:54:23Z and was open at inspection; its title is “feat(api): expose structured token usage records.” - HKUDS/nanobot issue #5266 was created 2026-08-06T07:26:50Z and was open at inspection; its title is “Logs about token consumption (too many tokens are burned).” - HKUDS/nanobot PR #5293 was created 2026-08-08T07:22:02Z and was closed at inspection; its title is “feat(usage): log per-iteration token diagnostics.” - The repository reported 46793 stars, 799 open issues, default branch main, and last push 2026-08-09T15:57:55Z. - The latest tagged-release baseline checked was v0.3.0 published 2026-07-25T08:08:47Z.
What changed
HKUDS/nanobot PR #5299 reports: Summary persist the latest 50 token-usage accounting records through the existing TokenUsageHook keep /api/settings/usage as the existing lightweight daily summary add authenticated GET /api/settings/usage/records?day=YYYY-MM-DD for on-demand diagnostics expose retention completeness explicitly through recorded_requests, retention_limit, and truncated include the recorded local day, source, session key, agent iteration, requested tool names, and a nested token-usage breakdown remove all UI, TypeScript type, translation, and frontend-test changes from this PR Protocol The summary response remains unchanged and does not embed detail records. The records endpoint returns newest-first retained records: A record is an accounted usage event captured by the existing hook. It is deliberately not specified as a raw provider HTTP call: retries or fallback finalization can be combined before the hook observes usage. requested_tools likewise describes tools requested by the model, not tools proven to have executed. The implementation adds no provider metadata interface, telemetry service, event framework, pagination layer, database, or frontend. Those can be justified separately if real requirements emerge. Addresses #5266. Testing uv run pytest tests/webui/test_token_usage.py tests/webui/test_settings_api.py tests/webui/test_settings_routes.py tests/command/test_builtin_dream.py tests/cli/test_gateway_runtime.py -q (139 passed) Ruff on
HKUDS/nanobot issue #5266 reports: Problem / Motivation I notice that nanobot consumes enormous amount of tokens. Like million just in some 2 hours without any noticable activity for the user. To trace this it would be nice to know when and which call produces which token consumption. Proposed Solution Log the token consumption on any heartbeat/dream/channel activity Alternatives Considered _No response_ Related Component Channel (WeChat, Feishu, Telegram, etc.) Additional Context _No response_
HKUDS/nanobot PR #5293 reports: Related to #5266 Problem Token usage is currently persisted as aggregated WebUI statistics by day and source. That is useful for understanding overall consumption, but it makes it difficult to identify which agent execution produced unexpectedly high token usage. For debugging normal conversations, cron/heartbeat runs, or dream executions, users currently lack a lightweight built-in diagnostic that identifies the session and agent iteration responsible for the usage. Solution Reuse the existing TokenUsageHook and AgentHookContext rather than introducing a separate telemetry subsystem. For each iteration with non-empty token usage, the hook now emits an INFO-level diagnostic containing the execution source, session key, iteration number, and token breakdown. The existing aggregation and persistence behavior remains unchanged. Changes Log per-iteration token usage from the existing TokenUsageHook Include source, session, iteration, prompt, completion, cached, total, provider-reported, and estimated token counts Reuse the existing usage normalization and source classification logic Keep the existing token-usage.json schema and aggregation behavior unchanged Add tests covering normal diagnostics, heartbeat attribution, empty usage, and estimated usage Testing python -m pytest tests/webui/test_token_usage.py -q — 12 passed python
Why it matters
Cost controls cannot act on totals that disappear inside free-form logs. Structured iteration records make compaction, retries and provider differences observable before a surprise bill becomes the only telemetry. The operator test is whether visible output, retained state and authority still describe the same event after retries, background work or restart.
Current
The primary record was open when captured on 2026-08-10. The tagged-release baseline was v0.3.0 published 2026-07-25T08:08:47Z. Repository metadata, full source bodies, current pull requests and issues, releases, Google News, Hacker News, Lobsters, Metamesh and the rendered ClawCharts row were inspected. ClawCharts selected the subject; it did not prove the claim.
Evidence
The primary URL is https://github.com/HKUDS/nanobot/pull/5299. Supporting records are https://github.com/HKUDS/nanobot/issues/5266 and https://github.com/HKUDS/nanobot/pull/5293. Source bodies, timestamps and states are preserved in the daily evidence bundle. Test counts and reproductions remain attributed to their authors unless identified as independently rerun.
Source boundary
Open work is described as open, closed work as closed, and operator reports as reports. A pull request is evidence of proposed or reviewed direction, not proof of a shipped release. Search residue, package mirrors and historically published source spines were excluded.
Operator take
Store bounded usage records with provider and model identity, expose aggregation separately from prompts, and label missing or estimated fields rather than converting uncertainty into zero. Preserve a before-state receipt, make the smallest reversible change, and verify the original failure independently.
Caveat
Public project records are mutable. Status, scope and evidence can change after publication. This brief records the inspected state and does not authorize changes to a reader’s deployment.
Source inspected; source state, environment and release boundary remain explicit.