Skip to content

Compaction and thinking

How /compact is run, and how Claude's summarized thinking reaches opencode.

Compaction

Compaction uses the selected transport. With transport: "auto", a CLI that definitively lacks the required headless flags uses a fresh interactive TUI instead. That TUI has no built-in tools, MCP servers, proxy, skill bridge or resumed session. The transcript and summary instructions are submitted as text, and the process is closed after its answer. The default remains headless.

When you run /compact in opencode, the plugin handles it on a short-lived dedicated Claude CLI spawn instead of routing it through your main conversation process. Three reasons:

  1. Cost. The summarizer reads your entire transcript every time. Routing through a smaller model keeps /compact from burning your Opus budget.
  2. Latency. Claude Haiku 4.5 hits ~150 tok/s with a hard 8k output cap, so compaction completes predictably (~30s for a long transcript).
  3. Cleanliness. The compaction spawn skips MCP servers, the tool proxy, and the multi-step continuation hint. It’s a one-shot text-out call; the rest is overhead.

The transcript itself is serialized rich: tool inputs and tool results are both included (each clipped at 10k chars), with oldest entries dropped first when the aggregate exceeds 180k chars. The summarizer sees actual tool activity rather than placeholders.

When compaction hits a usage limit

A compaction turn’s text is what opencode stores as the summary, so a compaction that failed must produce no text at all. It does not: the turn ends on an error, opencode marks the compaction failed and keeps the conversation it already had, and nothing is stored.

That matters because the alternative was measured and it is bad. Before this, a usage-limited compaction returned the CLI’s own sentence as an ordinary answer, opencode filed it as the summary, and from then on every session that could not resume its Claude transcript started from a conversation whose first line was “You’ve hit your session limit · resets 3pm” (issue #90). Messages before the summary were gone.

Every cause counts, not just a usage limit: an expired login, an account on hold, a billing problem, a failing result subtype. For all of them the summary would be wrong, so none of them is written. The cause is named in the error opencode shows, together with the CLI’s own sentence, and in a WARN in the plugin log.

There is nothing to configure and no way to turn this off. Retry the compaction once the account can serve again.

Compaction on a fork

With forkCompaction: true (off by default), a headless /compact does not render the thread as text. It branches the chat’s own Claude session with claude --resume <id> --fork-session and asks for the summary inside that copy, on the chat’s own model. The copy already holds the whole conversation, tool output and all, and it reads it from that model’s prompt cache. compactionModel is not used when it does.

What it costs, measured on Claude Code 2.1.314:

Thread Today (Claude Haiku 4.5, transcript) Fork on the chat’s model
136k tokens, Claude Haiku 5.5 $0.122, 12.2 s, kept 4 of 10 planted facts $0.013, 9.7 s, kept 10 of 10
81k tokens, Claude Opus 5.5 $0.055, 14.0 s, kept 11 of 12 $0.054, 13.6 s, kept 11 of 12
61k tokens, Claude Haiku 5.5, through the plugin $0.066, 12.2 s $0.002, 8.2 s, 98% of the input from cache

The long thread is where the transcript loses: it keeps the newest 180,000 characters, so a decision made early is gone before the summarizer reads anything. The fork sees all of it.

It is off by default because it is not cheaper in every case. It pays the chat model’s prices, so on Opus it costs about what today’s Haiku 4.5 transcript does, and a chat whose cache has expired (idle past its cache lifetime) has its whole thread re-read at the model’s cache-write price. A fork on a different model reads nothing from the cache (the cache is per model), which is why the fork always runs on the chat’s own.

The fork runs with no MCP servers and --permission-mode dontAsk, so it cannot reach opencode’s tools or write anything, and it is told to answer with the summary only. Its copy of the conversation is deleted when the summary is done; the chat’s own Claude session and transcript are never touched, and the chat carries on in its own process. A failed fork is a failed compaction exactly as above: no text, an error, nothing stored.

It falls back to the transcript, silently apart from one INFO line naming why, when the chat has no live claude process, a turn or a proxied tool call is still running, the chat moved to another account, its transcript is gone, or the CLI lacks --fork-session or dontAsk. The interactive transport always uses its own compaction.

Claude Code’s own idle compaction

Claude Code (2.1.299 and later) compacts a long conversation by itself when it has sat idle for most of its prompt cache’s hour: 54 minutes after the last request, when the conversation holds at least 200,000 tokens (CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS moves that, never below 100,000), the cache lifetime is one hour and the account is not near a limit. Your next message then starts from a summary instead of writing the whole conversation into the cache again.

  • On the default headless transport it never runs. Claude Code arms it only in its own TUI and for a fixed list of host apps (VS Code, Desktop and others), and a plugin spawn is none of those. Measured on Claude Code 2.1.322 over a 54-minute idle: a headless child sent nothing and wrote nothing between turns, and its next message carried the whole conversation. A chat idle for more than an hour writes its prompt cache again on its next message.
  • On the interactive transport it runs. Measured: the TUI compacted a 120,019-token conversation to 2,855 tokens 54 minutes after its last request, with no turn running. The plugin starts your next reply with a ▌ **context compacted:** note saying the conversation was compacted while it sat idle, with the before and after token counts.
  • To turn it off, put "idleCompaction": false in Claude Code’s own settings.json (the account’s config directory, ~/.claude by default). Measured: the TUI then keeps the whole conversation. The plugin leaves the choice to Claude Code: compacting costs one read of the cached conversation and a short summary, where letting the cache expire costs writing the whole conversation again.
  • The compaction’s own API call is in Claude Code’s usage but in no turn, so turnStats, maxBudgetUsd and the sidebar’s spend leave it out.

Picking a different compaction model

Source How Wins over
Env var (per-process) CLAUDE_CODE_COMPACTION_MODEL=claude-sonnet-4-6 opencode config, default
opencode.json (per-project) "compactionModel": "claude-sonnet-4-6" under provider.claude-code.options default
Default claude-haiku-4-5 –

Anything Claude Code’s --model accepts works as a value.

Extended thinking

The plugin forwards Claude’s thinking blocks (thinking_delta stream events) to opencode as reasoning parts, so the “Thinking” row in the chat panel shows whenever the model uses extended thinking. This works across every Claude 4 family model the CLI supports.

What you see is a summary of the model’s thinking, not the raw chain-of-thought. Anthropic stopped exposing raw thinking on the Claude 4 family and ships a server-generated digest instead. For Claude Opus 4.7 specifically, thinking content is omitted from responses by default; the plugin opts back in by passing --thinking-display summarized on every spawn. Claude Code CLI 2.1.142+ is required for that flag to take effect; older CLIs skip it silently.

Reasoning effort

Each model exposes five picker variants, low / medium / high / xhigh / max. An agent’s own reasoningEffort frontmatter accepts six values: those five plus minimal, which maps to the CLI’s low. The plugin hands the level to the CLI at spawn as --effort <level> on Claude Code 2.1.288 or newer, and as CLAUDE_CODE_EFFORT_LEVEL on older CLIs, the interactive transport, or with liveModelSwitch: false. Either way it is the session-wide override: it beats the effortLevel in that account’s settings.json, and a shell export of the same variable is left out of the spawn so it cannot override the level you picked. Effort is part of the session key. On Claude Code 2.1.288 or newer a change between two explicit levels is applied to the running process with Claude Code’s own apply_flag_settings request, so the process, its MCP connections and the prompt cache stay as they are (liveModelSwitch, on by default); a change of model is applied the same way with set_model. Otherwise, or if Claude Code refuses, changing effort retires the previous effort’s process, but not the conversation: the Claude session is carried over to the new effort’s key and the fresh process resumes it with --resume, so the thread is not replayed as text. It is a move, not a copy, so switching back carries it again rather than resuming anything stale; same-effort streaming turns still reuse their process. Set resumeAcrossModelChanges: false to go back to replaying. This reset is scoped to the same directory, model, provider/account, agent, and conversation. If the previous effort still has pending work (including tool results, plan approval, recovery, or /btw), that turn finishes on the previous process at its original effort, and the new effort applies from the next turn that finds it idle. A change to the agent’s cacheTtl, maxTurns or maxBudgetUsd, alone or together with the effort, is handled the same way. Title, compaction, and /btw calls do not trigger effort resets.

Earlier versions injected a thinking keyword such as (ultrathink) into the user message instead. Claude Code stopped recognising every keyword except ultrathink, so that path is gone and nothing is appended to your messages any more. Compaction skips request and agent effort overrides, but still inherits a shell-level CLAUDE_CODE_EFFORT_LEVEL when set.

Env-var overrides

The plugin respects the standard Claude Code thinking env vars. If you set them in your shell, they pass through to the spawned process untouched, with the one exception in the first row.

Env var Effect
CLAUDE_CODE_EFFORT_LEVEL=<level> Session effort override. Passes through when no effort was requested; a variant or an agent’s reasoningEffort replaces it for that spawn (on Claude Code 2.1.288 or newer it is removed from that spawn and the level goes as --effort).
CLAUDE_CODE_PROMPT_CACHE_TTL=5m|1h Prompt cache TTL for the whole machine. Passes through when no agent asked; an agent’s cacheTtl or defaultSubagentCacheTtl replaces it for that spawn.
CLAUDE_CODE_DISABLE_THINKING=1 Disable thinking entirely.
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 Disable adaptive thinking only.
CLAUDE_CODE_SHOW_THINKING_SUMMARIES=0 Suppress summaries (the plugin sets this to 1 by default when unset).

Free and MIT-licensed, made by @khalilgharbaoui. If the plugin saves you time, you can buy its maintainer a coffee.

Buy me a coffee