|
| 1 | +# Context usage meter |
| 2 | + |
| 3 | +The chat meter divides the latest observed context occupancy by the active |
| 4 | +context window. The numerator is the provider's current prompt/context size, |
| 5 | +not cumulative billing tokens for the entire conversation. |
| 6 | + |
| 7 | +Clicking the context pill opens a compact usage summary. When the provider |
| 8 | +supplies token details, **Token logs** opens a scrollable right sidebar. The |
| 9 | +sidebar can be closed with its close button, the backdrop, or Escape. Claude |
| 10 | +provides context categories; Codex, OpenCode, and Grok provide request or turn |
| 11 | +token counters, while CrewCoder provides session counters and its latest context |
| 12 | +input reading. These rows can overlap and must not be added together. |
| 13 | +If a provider reports token counts before a context window is known, the usage |
| 14 | +strip shows a direct **Token logs** button and the sidebar marks context usage |
| 15 | +as unavailable instead of showing a fabricated percentage. |
| 16 | + |
| 17 | +Codex token logs show the latest app-server request's input and output, plus |
| 18 | +cached input and reasoning output when reported. OpenCode logs show its latest |
| 19 | +assistant message's input, output, reasoning, cache read, and cache write |
| 20 | +counts. Grok logs show latest-call input/output and, when present, cache read, |
| 21 | +reasoning, and cumulative turn input/output. These providers do not expose |
| 22 | +Claude-style system/tool/message context categories through these usage events; |
| 23 | +the sidebar labels their rows as provider token counts rather than claiming |
| 24 | +they sum to context occupancy. |
| 25 | + |
| 26 | +CrewCoder token logs use the ACP `session/prompt` result's namespaced |
| 27 | +`crewcoder/usage` summary, falling back to its top-level `usage` mirror. They |
| 28 | +show the latest context input (`lastInputTokens`) separately from cumulative |
| 29 | +session input, output, total, cached input, cache write, and reasoning counts |
| 30 | +when those fields are reported. The session counters can span multiple models |
| 31 | +and requests and do not sum to the current context reading. If CrewCoder omits |
| 32 | +`lastInputTokens`, cumulative session totals remain visible in Token logs but |
| 33 | +do not become a context occupancy estimate. |
| 34 | + |
| 35 | +## Window sources |
| 36 | + |
| 37 | +Use these sources in order: |
| 38 | + |
| 39 | +1. A full window reported for the active session or turn by the provider bridge. |
| 40 | +2. A full window from the provider's model catalog, when it supplies one. |
| 41 | +3. A static model-family fallback, when no provider value is available. |
| 42 | + |
| 43 | +Codex app-server usage notifications include `modelContextWindow`. For known |
| 44 | +models, this can be smaller than the model's full window because it is the |
| 45 | +effective request prompt budget. CrewCode shows the known full model capacity |
| 46 | +as the meter denominator and labels the reported smaller value separately as |
| 47 | +**Codex prompt budget**. For unknown models, the reported value remains the |
| 48 | +only available window and drives the meter. A reported value larger than model |
| 49 | +metadata also takes precedence. The full model window can come from provider |
| 50 | +catalog metadata or CrewCode's static model fallback; the latter can be stale |
| 51 | +if a custom Codex configuration changes capacity. Compaction-drop inference |
| 52 | +uses Codex's reported prompt budget as its threshold denominator even when the |
| 53 | +displayed model window is larger. |
| 54 | +The latest request's input tokens are also treated as an authoritative context |
| 55 | +reading, so a decrease after native compaction is not replaced by an old floor. |
| 56 | +The app-server `model/list` response discovers models but does not document a |
| 57 | +context-window field, so model discovery alone cannot supply the Codex meter. |
| 58 | + |
| 59 | +Claude's SDK `getContextUsage()` supplies the active `maxTokens` (or |
| 60 | +`rawMaxTokens`) window. The meter sums its active categories and excludes |
| 61 | +deferred categories, unused space, and compaction headroom using each SDK row's |
| 62 | +`kind`, with legacy category handling for older Claude binaries. CrewCode |
| 63 | +requests `detail: 'full'`, since `summary` uses local estimates rather than |
| 64 | +the token-counted `/context` breakdown. The categorized SDK reading is the |
| 65 | +source of occupancy; result-message billing usage is separate and aggregates |
| 66 | +multiple requests. The static model table can |
| 67 | +still supply a window but cannot supply occupancy. Claude's `--help` does not |
| 68 | +provide a model-window catalog. |
| 69 | + |
| 70 | +CrewCode asks `getContextUsage()` after each assembled assistant message while |
| 71 | +the SDK query is active. It retries at the result only if no valid reading has |
| 72 | +arrived, because a result-time call can race query shutdown and a full reading |
| 73 | +can involve token-counting API requests. If no control reading succeeds for that turn, the latest |
| 74 | +individual assistant message's input and cache token counts provide a bounded |
| 75 | +request-context fallback. Only when neither current-turn source exists does |
| 76 | +CrewCode reuse an earlier measured reading; with no reading at all, the meter |
| 77 | +stays unknown. Result-message usage remains billing-only because it aggregates |
| 78 | +multiple requests in one turn. |
| 79 | + |
| 80 | +CrewCoder ACP usage can also include a live `contextWindow` and |
| 81 | +`lastInputTokens`; its bridge passes those through to the meter. Providers |
| 82 | +that report no usable window can show no percentage if no catalog or static |
| 83 | +fallback exists. A fallback percentage is an estimate, not a provider reading. |
| 84 | + |
| 85 | +The latest usage snapshot is persisted for resumed chats. A new provider |
| 86 | +report replaces its window; occupancy normalization and compaction handling |
| 87 | +are described in [Conversation storage](conversation-storage.md). |
| 88 | + |
| 89 | +## Automatic compaction |
| 90 | + |
| 91 | +Claude's `compact_boundary`, Codex app-server's `contextCompaction` completion, |
| 92 | +CrewCoder's `_crewcoder/compaction_update`, and OpenCode's matching |
| 93 | +`session.compacted` SSE event are native completion signals. They clear the |
| 94 | +previous context reading in the main process, its persisted snapshot, and the |
| 95 | +latest visible usage strip. The meter remains unknown until a new provider |
| 96 | +usage reading arrives; a pre-compaction reading must not be replayed at turn |
| 97 | +end. Historical provider token counters remain in Token logs, while old |
| 98 | +Claude context categories are cleared. OpenCode's event is accepted only for |
| 99 | +the active session. |
| 100 | + |
| 101 | +When no native boundary is observed, a high-occupancy to large-drop usage |
| 102 | +reading can detect compaction for Codex, CrewCoder, OpenCode, and Grok. The |
| 103 | +smaller observed reading becomes the new context baseline. Providers without |
| 104 | +an observed boundary or trustworthy absolute context reading are not inferred |
| 105 | +from silence or a completed turn. |
0 commit comments