agent-token-usage

summarize per-agent llm token consumption for openclaw multi-agent setups by parsing trajectory logs. use when asked "how much token did agent X use today", "which agent burns the most tokens", "token usage breakdown", or "billable token estimate". returns a ranked table with input, output, cacheRead, cacheWrite, total tokens, and optional billable-equivalent estimate. not for dollar cost (use model-usage skill), per-message inspection (use sessions_history), or non-openclaw runtimes.

ships two delivery mechanisms: a cli (python, zero setup) and an optional 📊 button injected into control ui's header next to search.

intent

trajectory logs record the authoritative usage object for each llm call, while sessions_list only returns the last context window size (not cumulative consumption). for long-running sessions, real token burn is 100x+ larger than sessions_list reports. this skill walks trajectory.jsonl files, sums usage objects per agent per day, and surfaces the true cost breakdown across input, output, cache reads, cache writes, and billable-equivalent tokens. use this to answer "who's actually burning compute today" and "which agent is most expensive".

inputs

required:

• openclaw runtime installed at ~/.openclaw/ with agents running sessions
• trajectory logs at ~/.openclaw/agents/<agent-name>/sessions/*.trajectory.jsonl in jsonl format, each line a json event with optional usage dict and ts (iso8601 timestamp)

optional (for ui button):

• write access to ~/.openclaw/workspace/skills/agent-token-usage/ (injected iife payload)
• write access to control ui dist directory (patched bundle)
• macos with launchd (for auto-refresh job); linux users must run refresh-data.sh via cron or systemd timer

environment / external:

• no external api calls; all processing is local filesystem reads
• no auth required

procedure

cli workflow

1. invoke the aggregator script with optional flags: python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py [--date YYYY-MM-DD] [--billable] [--format json|table]

   • input: script path, optional date (defaults to today in local timezone), optional format flag
   • output: printed table or json to stdout

2. walk agent trajectory files at ~/.openclaw/agents/*/sessions/*.trajectory.jsonl

   • input: filesystem paths
   • output: file handle list in memory

3. for each trajectory file, read line-by-line (jsonl format)

   • input: file content, target date string
   • output: parsed event objects

4. filter events by date using ts field (iso8601 timestamp)

   • input: event ts value
   • output: events matching target date only

5. dfs-search each event's data field for a usage dict containing input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens

   • input: event dict
   • output: usage object or null

6. accumulate token counts per agent into running totals for input, output, cacheRead, cacheWrite

   • input: usage dict, agent name
   • output: per-agent token sums

7. compute total tokens as sum of input + output + cacheRead + cacheWrite

   • input: four token counts
   • output: total token integer

8. if --billable flag set, compute billable-equivalent tokens using formula: (cacheRead × 0.1) + (cacheWrite × 1.25) + input + output

   • input: token counts, billable flag
   • output: billable-equivalent integer or omitted if flag not set

9. sort agents by total tokens descending

   • input: per-agent dict
   • output: ordered list

10. render output as table (default) or json (if --format json)

    • input: sorted agent data, format flag
    • output: printed table or json string

ui button workflow (optional)

11. run apply-ui.sh to inject button into control ui

    • input: script, control ui bundle path
    • output: patched control ui bundle with iife payload, installed launchd refresh job

12. launchd auto-refresh (macos only) fires every 5 minutes and runs refresh-data.sh

    • input: time interval
    • output: ~/.openclaw/workspace/skills/agent-token-usage/control-ui/data/agent-token-usage.json written with latest token counts

13. user clicks 📊 button in control ui header

    • input: click event
    • output: modal dialog opens

14. modal fetches same-origin json from ../data/agent-token-usage.json (relative to control ui origin)

    • input: same-origin fetch request
    • output: json response with per-agent breakdown

15. modal renders table with columns: agent name, input, output, cacheRead, cacheWrite, total, ~bill (if present)

    • input: json response
    • output: rendered html table in modal

16. run remove-ui.sh to uninstall button and refresh job

    • input: script
    • output: control ui bundle restored, launchd job deleted, data dir removed

decision points

if user provides --date flag:

• use provided iso8601 date string; else use today's local date

if user provides --billable flag:

• compute and append ~bill column to output; else omit billable-equivalent tokens

if user provides --format json:

• output json array of objects; else output human-readable table

if trajectory file has no usage dict in event:

• skip that event (non-llm tool calls are excluded by design)

if no events match target date:

• output empty table or empty json array with zero grand totals

if ui button already installed (apply-ui.sh run twice):

• idempotent behavior: re-patch bundle, reinstall launchd job

if launchd refresh job cannot write to data directory:

• silently skip write (does not crash modal; user sees stale data)

if control ui bundle was overwritten by openclaw update:

• re-run apply-ui.sh (idempotent); iife patch is reapplied

if running on linux:

• launchd auto-refresh does not apply; user must manually invoke refresh-data.sh via cron or systemd timer, or call cli script directly each time

if date string in --date does not match any trajectory timestamps:

• output empty table with zero counts

if cacheRead, cacheWrite, or input/output tokens are missing from usage dict:

• treat missing field as 0 (do not crash)

output contract

cli table format (default):

• stdout: human-readable ascii table with columns: agent, input, output, cacheRead, cacheWrite, total, optionally ~bill
• format: one row per agent, sorted by total descending
• grand total row at bottom
• exit code 0 on success, 1 on file read error or invalid date format

cli json format (--format json):

• stdout: json array of objects, each with keys: agent, input, output, cacheRead, cacheWrite, total, optionally billable
• format: utf-8, one object per agent, sorted by total descending
• no grand total object
• exit code 0 on success

ui data file (agent-token-usage.json):

• location: ~/.openclaw/workspace/skills/agent-token-usage/control-ui/data/agent-token-usage.json (created by refresh-data.sh, served by control ui origin)
• format: json object with keys: timestamp (iso8601 when written), date (YYYY-MM-DD), agents (array of per-agent objects)
• each agent object has: name, input, output, cacheRead, cacheWrite, total, optionally billable
• refresh cadence: every 5 minutes (launchd on macos) or manual (linux)

outcome signal

cli success:

• printed table or json appears on stdout with non-zero token counts for at least one agent
• output is sortable by total tokens (largest agent at top)
• if --billable flag used, ~bill column shows cacheRead-heavy agents as cheaper, input-heavy agents as more expensive
• exit code 0

cli failure:

• stderr prints error message (file not found, invalid json in trajectory, invalid date format)
• exit code 1
• no partial output

ui button success:

• 📊 button appears in control ui header next to search after apply-ui.sh runs
• clicking button opens modal with table of per-agent token counts
• table matches latest trajectory data (refreshed within 5 minutes on macos, or manually on linux)
• button persists across page reloads
• localStorage toggle milly.tokenUsageBtn can be set to 'off' to hide button per-browser without uninstalling

ui button failure:

• button does not appear after apply-ui.sh (check if control ui dist path is correct)
• modal fetch fails with cors error (means data file not written; run refresh-data.sh manually)
• after openclaw update overwrites dist, re-run apply-ui.sh and button reappears