Context Visualizer Plugin

Shows what actually fills the model's context window: system prompt, tool
definitions, any compaction summary, the notes the harness injects, and the
conversation turn by turn — as a stacked-bar transcript card and on demand via
/context.

The plugin does not re-assemble the prompt to answer these questions. It
caches the exact message list and tool list sent to the model (after every
prompt-rewriting plugin, such as Context Summarization,
has had its turn) and reads the real token counts the model's response
reports, so the breakdown always describes what was actually sent — not an
estimate of what would be sent next.

Configuration

plugins:
  - module: codumentor.plugins.context_visualizer
    class: ContextVisualizerPlugin
    args:
      threshold_percent: 50
      threshold_tokens: null
      cadence: each_turn

All args are optional.

Arg	Type	Default	Description
threshold_percent	float	50	Share of the model's declared context window (models.agent_context_window / a profile's context_window) that a turn's prompt must reach before a card is shown. 0 = show one on every turn. Clamped to 0–100.
threshold_tokens	int \	null	null
cadence	each_turn \	crossing	each_turn

The snapshot behind the card is always computed and cached for the
conversation, whatever the threshold — only showing a card is gated. This
is what lets /context show a breakdown on a conversation that has never
crossed the configured threshold.

Each user can override threshold_percent and cadence for themselves in
Settings → Extensions → Context Visualizer; the stored per-user value wins
over the YAML default when present.

When a card appears

At most one card per turn — a turn with eight tool calls makes eight LLM
calls and used to post eight nearly identical cards.

• The crossing. The first call whose prompt reaches the threshold shows a card immediately, mid-turn: the window filled up now and the run may have more tool calls to go. A compaction that drops the window back under the threshold re-arms this, so a long session gets a card each time the pressure returns.
• The end of a turn still above the threshold — the moment the user is next in a position to do something about it. Set cadence: crossing to keep only the crossing card.

A prompt below the threshold shows nothing at all; /context is how you look
anyway. threshold_percent: 0 (or threshold_tokens: 0) means every turn is
above the threshold, so every turn ends with a card — and there is no crossing
to report, whatever cadence says.

/context

Type /context to see the breakdown for the current conversation right now,
regardless of the threshold. It re-emits the newest cached snapshot — it does
not trigger a model turn or re-assemble the prompt. On a conversation with no
turns yet, it returns a notice instead of a card.

What you see

Closed — one line and one bar:

⊺ Context  64%  167k / 262k · +41k                                       ▸
███▐██▐████│███████│████│██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
■ System prompt 20k   ■ Tool definitions 12k   ■ Compaction summary 24k
■ Injected notes 4.4k   ■ Conversation 106k · 12 turns

The blocks stack in a fixed order, so the bar is learnable:

• System prompt — the assembled system message
• Tool definitions — the tool schemas, counted per tool
• Compaction summary — present only once Context Summarization has compacted the window, and then often the largest single block in it
• Injected notes — the notes the harness and plugins add to every prompt (a UI-rendering reminder, an environment block, a recalled memory). They carry the user role, so before they were counted separately each one opened a phantom "turn" and its tokens were charged to the user
• Conversation — the turns themselves, ruled at each turn boundary so a single runaway turn is visible as the widest division
• Free — the room left, when the model declares a window

+41k is the growth since the previous card, which is the number that says how
many more turns the window has room for. A percentage at or above 85% reads as
a warning. When the window has not yet reached the threshold (the /context
case), a small mark under the bar shows where it sits.

Open — three tables, each carrying the row that makes it add up to the bar:

1. What fills the window — every block with its tokens and share, then the Used total.
2. Conversation, turn by turn — one row per turn with a fixed column for each role (user, assistant, tool calls, tool results; a role a turn never used prints a rule, so the columns stay comparable), a bar scaled against the largest turn, and the conversation total. A long conversation keeps the most expensive and the most recent turns and sums the rest into one row.
3. Tool definitions — the largest by name, the remainder in one row, then the total.

A footnote names the model, what the reply cost, the growth since the previous
card, and the threshold this card appears from.

If the model declares no context window, the card still renders the block
breakdown but cannot show a "Free" segment or a percentage — the plugin never
guesses a window to draw against.

Notes

• The card and /context describe the last LLM call of a turn, not a running estimate. Usage is reported from a background task, so the card waits for every call the turn started to report before drawing; otherwise it would draw the second-to-last prompt and understate the window.
• Per-block figures are local tokenizer estimates, scaled uniformly so they sum to the prompt total the API reported. The bar therefore adds up to what was billed, while the proportions come from the estimator.
• tool_runtime usage events are ignored — the snapshot only tracks the main chat completion calls whose prompt was actually assembled and cached.
• Enterprise edition only; not shipped in the Community edition.