OpenCode compaction config for local providers
Parent: Mac local LLMs: Agent clients, context and compaction · Published reference · snapshot 2026-10-05
↓ Facts as markdownall context files
V2 settings: compaction.auto (default true), compaction.keep.tokens (default 15000, recent conversation kept beside the summary), compaction.buffer (default 10% of the limit, tokens kept free; larger starts compaction earlier). Both numbers are non-negative integers.
These notes link each claim to its source. A source may be a research report hosted on this site rather than the primary document. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Facts
- V2 settings: compaction.auto (default true), compaction.keep.tokens (default 15000, recent conversation kept beside the summary), compaction.buffer (default 10% of the limit, tokens kept free; larger starts compaction earlier). Both numbers are non-negative integers. [source]
- auto also covers recovery: a request the provider rejects as too long is compacted and retried once; a second rejection is returned as an error. [source]
- The summary is written by the session's own model; there is no separate compaction model. [source]
- Compaction needs older conversation to replace and cannot make room when a request is mostly fixed instructions and tool schemas (docs example: 128k context = 120k fixed + 8k conversation). [source]
- If the conversation to compact is itself too long, OpenCode sends a shortened text version and may omit the oldest exchanges. [source]
- Native provider compaction (settings.compaction.type native) works only for OpenAI Responses models; local providers use summary compaction. [source]
- After compaction, current instruction files become the session baseline. [source]
- OpenCode estimates tokens locally when provider usage is missing, so buffer cannot guarantee no overflow. [source]
- V1 (opencode.ai/docs/config, still cached as current there): auto, prune (default false), reserved (token buffer so compaction itself does not overflow). V2 (opencode.ai/v2/docs/compaction, bswen guide updated 2026-09-07): auto, keep.tokens, buffer; the V2 migration note says V1 used tail-turn and pruning behavior. [source]
- Issue 8140 (2026-01-13, closed not planned) asked for compaction.threshold (0-1) and compaction.maxContext to compact earlier than the model limit; not adopted, so buffer is the V2 way to compact earlier. [source]
- A fixed prefix of tens of thousands of tokens (skill listing, MCP tools) leaves compaction unable to help on a small window (see agent-skill-listing-injection-cost.md). [source]
- V1 docs page versus V2 docs page describe different keys under the same name compaction; which applies depends on the installed OpenCode version. [source]
- Which config schema OpenCode 1.18.34 (the version measured locally) accepts. [source]
- Whether limit.context is required for buffer to take effect on a custom local provider; the bswen guide lists limit.context as the budget basis. [source]
- OpenCode V2 compaction keys are auto (true), keep.tokens (15000) and buffer (10% of the limit by default) [source]
- OpenCode V2 recovers once from a provider too-long rejection and returns the second rejection as an error [source]
- OpenCode compaction uses the session's model and has no separate compaction model [source]
- OpenCode compaction cannot create room when fixed instructions and tool schemas fill the window [source]
- OpenCode V1 config keys are auto, prune and reserved [source]
- V2 uses compaction.keep.tokens instead of V1 pruning and tail-turn behavior [source]
- Issue 8140 asking for compaction threshold and maxContext was closed as not planned [source]
- OpenCode estimates tokens locally when provider usage is missing, so buffer cannot guarantee overflow avoidance [source]
- Native provider compaction applies to OpenAI Responses models only [source]
- For a small local window set limit.context to the server's real n_ctx and raise buffer, since there is no threshold setting [source]
Corrections and disagreements
- CONTRADICTS: claude-code-context-window-mismatch-against-local-servers.md lists reserved and prune as the compaction config; that is the V1 schema, and a V2 install uses keep.tokens and buffer. [source]
Children
- No children recorded.