context-usage

The context-usage extension adds a /context command that shows how the active context window is allocated.

Usage

/context

Fresh-session behavior

When usage is unknown (for example immediately after compaction or right after /new//clear), /context shows the standard no-data warning instead of rendering a misleading 0 tokens chart.

Categories shown

Category	What it measures
System prompt	Base instructions
System tools	Tool definitions
Context files	AGENTS.md, CLAUDE.md
Skills	Available skill metadata in prompt
Messages	Conversation history
Free space	Remaining capacity
Autocompact buffer	Reserved compaction buffer

Historical tool-result memory

/context includes a Historical tool-result payloads block:

• total tool results in the active branch
• summarized result count
• retained bytes in memory
• reclaimed bytes from summarization

This reflects the toolResultRetention policy.

toolResultRetention settings

{
  "toolResultRetention": {
    "enabled": true,
    "keepRecentToolResults": 12,
    "maxRetainedBytesPerResult": 49152,
    "previewChars": 600
  }
}

Semantics:

• keepRecentToolResults: newest N results kept full
• maxRetainedBytesPerResult: older results above this are summarized
• previewChars: maximum summary preview size

Context budget guardrails

Tallow also applies pre-flight and ingestion-time guardrails for tool output.

contextBudget settings

{
  "contextBudget": {
    "softThresholdPercent": 75,
    "hardThresholdPercent": 90,
    "minPerToolBytes": 4096,
    "maxPerToolBytes": 524288,
    "perTurnReserveTokens": 8000,
    "unknownUsageFallbackCapBytes": 32768
  }
}

These values drive:

• per-turn planner envelopes for tool-call batches
• ingestion-time tool-result truncation under pressure
• unknown-usage fallback behavior (tokens: null)

Budget signal in system prompt

Each turn includes a short signal line in the system prompt:

• known usage: Context budget: <percent>% used, ~<remaining>k tokens remaining
• unknown usage: Context budget: unknown (waiting for fresh usage sample)

Unknown usage is treated as high risk and uses conservative caps.