Token Report Plugin

The Token Report Plugin contributes a Token Usage section to the end-of-session report produced by the Console Report plugin. It accumulates token data across all LLM calls during the session and renders a formatted summary with per-query breakdowns and an ASCII bar chart.

Overview

The Token Report plugin:

1. Accumulates token counts from each LLM call via the onUsageTracked hook
2. Contributes a "Token Usage" section when onSessionReport fires (console format only)
3. Reports: model name, estimated cost, total tokens, input/output breakdown with visual bars, per-query averages, session duration, and a per-query bar chart

Configuration

plugins:
  - module: codumentor.plugins.token_report
    class: TokenReportPlugin

No configuration parameters are needed.

Report Output

The token report section is printed at the end of the session (assembled by the Console Report plugin):

Token Usage
-----------
Model: gpt-4o  Cost: $0.0124
Total Tokens: 15.2K  Queries: 8

Input:    12,400 ( 81.6%) ████████████████░░░░
Output:    2,800 ( 18.4%) ████░░░░░░░░░░░░░░░░

Per Query Avg: Total: 1900.0  Input: 1550.0  Output: 350.0
Duration: 47.3s

Per-query token usage (bars show relative token counts)
██ ████ ██ ██ ████ ██ ░░ ██

Hooks Used

Hook	Priority	Purpose
onUsageTracked	100	Accumulate per-iteration token data
onSessionReport	100	Build and return the Token Usage section

Notes

• Requires Console Report to be enabled — that plugin assembles and prints all contributed sections
• Only renders for format: "console" session reports
• Falls back to agent_summary from the report payload if no onUsageTracked data was collected (backward compatibility with older agent versions)