Skip to Content
IDEsOpenCodeContext

OpenCode context usage — see, limit, and reduce

To see how much context OpenCode is using, check the session sidebar in the TUI — it shows context fill as a percentage of the model window. To limit context, set limit.context on custom models, enable compaction/prune, start new sessions per task, and disable unused MCP servers that inject tool schemas every turn.

Hub: Tokenminning in OpenCode.

How do I see context usage in OpenCode?

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

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

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

There is no separate “context usage dashboard” URL — the TUI sidebar is the authoritative live meter.

Context window limits

Context includes everything resent on each agent turn:

SourceWhat counts
AGENTS.md, rules, skills metadataInput tokens every turn
MCP tool schemasEvery enabled server, every turn — even when tools are not called
Session transcriptAll prior messages and tool outputs
Reasoning modelsThinking tokens add output pressure — change reasoning effort on Plan, not Build
@ file attachmentsFull file contents referenced

Run opencode stats --tools after enabling a new MCP server to measure schema overhead.

Override catalog defaults when you want earlier compaction:

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

User-defined limit.context overrides catalog defaults — useful when a model advertises 1M context but you want compaction sooner. Details: Providers.

Compaction

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}
FieldDefaultEffect
autotrueSummarize when context nears limit (hidden compaction agent — costs tokens once)
prunefalseStrip old tool outputs while keeping recent ones — set true to opt in
reserved—Token buffer left for the compaction call itself

Official default for prune is false. Enable it explicitly when long sessions accumulate tool output bloat.

Manual compaction in the TUI:

/compact

Alias: /summarize. See TUI commands .

Disable auto-compaction if you always use new sessions per task:

export OPENCODE_DISABLE_AUTOCOMPACT=true

V2 compaction fields

Newer OpenCode releases may use keep.tokens and buffer instead of prune/reserved. See Compaction docs  for your version.

Compression and pruning

Compression (/compact, auto-compaction) summarizes older transcript into a shorter block — it costs tokens once but frees window space. Pruning (prune: true) removes stale tool outputs without a full summarize pass.

TechniqueConfig / commandWhen to use
Auto-compactcompaction.auto: trueLong sessions that approach the window
Manual compact/compact in TUISidebar at ~70–80% before Build explores
Prune tool outputscompaction.prune: trueAgent-heavy sessions with large read/bash results

Pruning

prune: true strips old tool outputs while keeping recent ones — opt in explicitly (default is false). Pair with /compact when long sessions accumulate tool output bloat.

Reducing unnecessary context

How MCP affects context

Each enabled MCP server adds tool JSON schemas to every agent turn. Five overlapping servers can exceed a modest model window before your actual prompt.

Disable MCP servers you are not using this week:

{
  "mcp": {
    "github": { "enabled": false },
    "playwright": { "enabled": false }
  }
}

Full patterns (per-agent toggles, org remote defaults): MCP guide.

Cap agent steps when loops are the problem:

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

Combine with permission.bash: "ask" (Agents).

Practical ways to avoid filling the context window

TechniqueSavings
New session per taskStops transcript compounding
Short AGENTS.mdRules
Disable unused MCPMCP
Haiku on Plan, not thinking modelsChange reasoning effort in OpenCode
Narrow @ mentionsOne file, not whole trees
/compact once, then new sessionCompaction is not free

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.

Last updated on
RulesMCP