how-it-works.md

How the plugin works

This guide explains how the plugin collects the data. It describes how the plugin computes the rate.

The data source

The plugin reads the token data from the current session. It reads the same data from the child sessions. A child session is a subagent.

The API requests

An assistant message can contain many provider steps. Each step is one API request. The plugin reads the step data from the message parts. It looks for parts of the type step-finish.

When the parts have no step data, the plugin reads the totals of the whole assistant message. The step data is more exact than the message totals.

The plugin counts the API requests. It also counts the requests that read from the cache and the requests that write to the cache.

The messages

The plugin reads the messages of a session. It counts only the assistant messages. An assistant message has a token count.

The plugin ignores the messages of the user. A user message has no tokens. The summary messages also have no tokens.

The token counts

The plugin reads four values from the assistant messages.

• input is the number of input tokens that are not served from the cache. The dialog refers to it as the fresh input.
• cache read is the number of tokens that came from the cache.
• cache write is the number of tokens written to the cache.
• reasoning is the number of reasoning tokens.

The plugin adds the values of the main session. Then it adds the values of each subagent. The totals are cumulative over every request in the session. A long session can show a cache read total that is much larger than the context window. Every request re-reads the same cached prefix, so the cache read count grows with each request.

The rate formula

The plugin computes the rate with the formula:

hit = cache read / (input + cache read)

The rate is a percentage. The plugin shows n/a when the sum of the values is zero. A session with no tokens gives no rate.

The plugin maps the rate to a verdict word and a color. The mapping has four levels. The levels are Excellent, Good, Fair, and Poor. The mapping is in docs/colors.md.

The plugin excludes cache write from the rate. A cache write is a one-time priming cost. It is not part of the input that the provider serves again.

The model list

The plugin groups the messages by model. Each group gives one row. The row order depends on the cache hit rate. The model with the highest rate is first.

The data read order

The plugin tries the read with the API first. If the API returns no messages, the plugin reads from the local state. This keeps the data current in the dialog.

The limits

The dialog shortens long model names, long session titles, and long subagent names. A shortened name ends with …. It shows all subagents. When there are many, the dialog scrolls.

The plugin does not change the data. It only reads the data. You can run it many times on the same session.