OpenCode context management

OpenCode context grows every turn: rules, MCP schemas, transcript, and tool outputs all resend until you compact, prune, or start a new session.

This page covers opencode context percentage, compaction settings, and opencode prune context patterns.

Hub: Tokenminning in OpenCode.

Read context usage percentage

OpenCode shows context fill in the session sidebar of the TUI — percentage of the model window consumed by configuration + transcript + tool outputs.

Sidebar level	Action
< ~70%	Normal — keep working
~70–80%	Run `/compact` or plan a new session
> ~80%	New session before Build explores further
Compaction runs repeatedly	Session grows faster than pruning removes — new session per task

opencode stats measures billing; the sidebar is the live guardrail. See Token usage.

Compaction and pruning

OpenCode manages long sessions via Config: compaction :


{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

Field	Effect
`auto`	Summarize when context nears limit (hidden `compaction` agent — costs tokens once)
`prune`	Strip old tool outputs while keeping recent ones
`reserved`	Token buffer left for the compaction call itself

Manual compaction in the TUI:


/compact

Alias: /summarize. See TUI commands .

Compaction is not free — it calls the model. Prefer shorter sessions over endless compact-and-continue.

V2 compaction fields

Newer OpenCode releases may use keep.tokens and buffer instead of prune/reserved. See Compaction docs for your version. Same principle: retain a recent tail, summarize the rest.

Set accurate context limits

If the catalog overstates a model’s window, compaction triggers too late:


{
  "provider": {
    "my-provider": {
      "models": {
        "my-model": {
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  }
}

User-defined limit.context overrides catalog defaults — useful for cost control on models that advertise 1M context but you never need it. Details: Providers.

Trim what fills context

Source	Reduction
MCP schemas	Disable unused servers
`AGENTS.md`	Short rules — Prompt hygiene
Large `read` / `grep`	Prune old outputs; scope `@` mentions
Reasoning models on Plan	Thinking tokens add pressure

Agent step limits

Cap Build iterations:


{
  "agent": {
    "build": {
      "steps": 25
    }
  }
}

Combine with permission.bash: "ask" if shell loops are the problem (Tools & permissions ).

New session per task

Start a new session when:

You finish one task and begin another
Sidebar context is above ~70%
Compaction already ran once on the same thread
The agent loops on a stuck problem

Switch with /sessions or command palette (ctrl+p). See TUI .

Troubleshooting

Context overflow errors — Run /compact; new session; verify limit.context for custom providers.

Compaction runs often — Prune is working but you add tokens faster than removal. New session per task.

Context mode queries — OpenCode does not expose a separate “context mode” toggle; behavior is compaction + limits + session boundaries above.