Context & Compaction

Every provider has a finite context window. Caliban tracks utilization in real time and provides several tools — automatic and manual — to keep long sessions healthy without losing important history.

Context tracking

Caliban maintains a ContextWindow counter that accumulates token usage from every provider response. This is independent of the telemetry subsystem: the /context command and the TUI status-bar percentage work for all users regardless of whether CALIBAN_ENABLE_TELEMETRY is set.

/context
  input tokens used : 62 430 / 200 000  (31%)
  output tokens used: 4 812
  ⚠ approaching limit (warn threshold: 80%)

/context shows a per-message-kind breakdown and warns when utilization reaches 80%. See Telemetry & Cost for OTLP export of context metrics.

Auto-compaction

When the context-window utilization reaches auto_compact_threshold, caliban automatically runs the configured compactor before the next turn. The default threshold is 0.75 (75% utilization).

Configure in settings.toml:

auto_compact_threshold = 0.75   # 0.0–1.0; unset or null disables autocompact

Set auto_compact_threshold to null (or omit it) to disable autocompact entirely and rely on manual /compact invocations.

Compaction strategy

Both autocompact and manual /compact run the compactor selected by compact_strategy:

compact_strategy = "summarize"   # "summarize" (default) | "drop-oldest" | "noop"

summarize and drop-oldest keep leading system messages and the most recent turns verbatim, and only act once utilization is high enough that there is older history to shed. Unknown values fall back to summarize.

Micro-compaction

Micro-compaction is an LLM-free per-turn pass that supersedes stale ToolResult blocks in the conversation history without making any API calls.

The logic is per-tool:

When a newer result for the same key exists, the older result block is replaced with a [superseded: <tool>(<key>)] placeholder, keeping message structure intact but recovering tokens.

Enable or disable in settings.toml:

micro_compact_enabled = true    # default: true

Manual /compact

/compact triggers an immediate compaction of the current conversation through the configured Compactor (the same path used by autocompact). A compact.event log entry is emitted and a compact.event metric is recorded if telemetry is enabled.

/compact

No flags. The strategy is determined by compact_strategy (see Compaction strategy above) — see Hooks for the PreCompact / PostCompact hook events that fire around each compaction.

/clear

/clear resets the conversation to an empty state and zeroes the ContextWindow counter. The session file is updated. Use it to start a fresh sub-task without opening a new session.

/clear

PreCompact and PostCompact hooks

Caliban fires PreCompact before compaction begins and PostCompact after it completes. These hook events are available to external scripts and MCP handlers.

# In settings.toml [hooks]
[hooks]
PreCompact  = [{ type = "command", command = "echo compacting…" }]
PostCompact = [{ type = "command", command = "notify-send 'compact done'" }]

See Hooks for the full hook configuration reference.

Prompt caching

Caliban uses Anthropic-style prompt caching by default to reduce cost on repeated turns. A cache marker is placed on the last user message when its estimated token count meets the minimum threshold.

Configure min_cache_block_tokens in settings.toml:

min_cache_block_tokens = 1024   # omit to use the upstream default

Tool result size cap

Caliban can cap the character length of individual tool results before they are appended to the conversation. This prevents a single large Read or Bash output from consuming a disproportionate share of the context window.

tool_result_cap_chars = 65536   # 0 disables the cap (default)

Summary of relevant settings