Skip to content

Compaction

For long sessions, /compact summarizes earlier turns to cut token cost while preserving the working context.

Manual compaction

/compact            # keeps the 10 most-recent messages, summarizes the rest
/compact --keep 20  # keep 20 most-recent messages

Currently all earlier messages including MCP tool calls are summarized to prose. Pair-preserving compaction is a future milestone.

PreCompact hooks (configured under hooks.PreCompact) fire synchronously before each compact.

Token counting and reporting

On completion, /compact reports actual token counts:

compacted 15 → 11 messages (~820 → ~210 tokens)

Token counting uses: - OpenAI-family models — real BPE tokenizer via tiktoken-go - Claude and others — char/4 approximation

Image tokens are not counted client-side; the provider's EventUsage is authoritative for image cost.

Auto-compaction

Set auto_compact_threshold to automatically run /compact when cumulative token usage since the last compact exceeds the threshold:

auto_compact_threshold: 150000   # tokens; 0 = disabled (default)

Or pass it on the command line:

anthrogo --auto-compact 150000

The threshold is checked at the end of every turn using the usageSinceLastCompact counter — not just the latest turn's usage — so sessions with many small turns are handled correctly. After a successful compact the counter resets to zero. Manual /compact also resets the counter.

/usage

Inspect the current state at any time:

/usage
Session totals: 1,240 input + 380 output = 1,620 tokens
Since last compact: 420 input + 130 output = 550 tokens
Auto-compact at: 150,000 tokens (keep recent: 10) — 149,450 tokens until trigger

The TUI status line shows tok: <in>in/<out>out (since: <Z>) [⚙ <N>] where since is the post-compact accumulation and ⚙ N is the auto-compact threshold (omitted when disabled). Live 1 Hz status refresh during turns.

Budget reset on compact

To zero the cost counter when compacting (e.g. to start fresh against a budget cap):

/compact --reset-budget

This resets the in-memory usage counter so the post-compact session starts fresh. The budget cap remains armed; usage accumulates again from zero.