Warming

Session warming sends periodic model requests to preserve provider-side prompt caches or other short-lived state while you pause between prompts. It is disabled by default.

Enable warming in any OpenCode configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "warming": true,
}

With this configuration, OpenCode warms a recently active session after four minutes without a model request. It continues every four minutes until 30 minutes have passed since the latest non-warming request.

Options#

Use the object form to change the warming prompt, idle interval, or active window:

{
  "$schema": "https://opencode.ai/config.json",
  "warming": {
    "prompt": "Do not perform any work. Reply with exactly: OK",
    "interval": "5 minutes",
    "duration": "1 hour",
  },
}

Omitted object fields keep their defaults. For example, this changes only the interval:

{
  "warming": {
    "interval": "2 minutes",
  },
}

Automatic interval#

Set interval to "auto" to warm just before each model’s prompt cache expires. OpenCode uses 90% of the model’s cache.ttl setting, so a "5m" cache is warmed every 4.5 minutes. Models without a cache.ttl are not warmed.

{
  "warming": { "interval": "auto", "duration": "2 hours" },
  "providers": {
    "anthropic": { "settings": { "cache": { "ttl": "1h" } } },
  },
}

The interval must be shorter than duration, so raise duration for long cache lifetimes such as "1h". Otherwise OpenCode skips warming and logs a warning.

Durations#

interval and duration accept duration strings. Both must resolve to finite values greater than zero, and interval must be shorter than duration; otherwise OpenCode skips warming and logs a warning.

{
  "warming": {
    "interval": "30 seconds",
    "duration": "1 hour",
  },
}

Timing#

Warming starts after a non-warming model request. After a warming request finishes, the next idle interval starts, but the active window is not extended.

00:00  normal model request
00:04  warming request
00:08  warming request
00:30  warming stops

Any new non-warming model activity resets both timers. If the interval is as long as or longer than the duration, the active window expires before a warming request is sent.

00:00  normal model request
00:20  normal model request; window restarts
00:24  warming request
00:50  warming stops

Requests#

A warming request uses the session’s current model, agent, instructions, and conversation context. OpenCode appends the configured prompt transiently, makes one model call, and discards the response.

[current session context]
[transient user message: keep-alive prompt]
→ one model response, discarded

The request does not admit input, add messages to history, or mutate durable session state. OpenCode does not dispatch local tool calls or continue a tool loop; the default prompt also tells the model not to use tools.

Failures#

Warming failures are logged without failing or changing the session. OpenCode waits until the next interval before trying again, while the original active window continues to count down.

00:04  warming request fails; session is unchanged
00:08  next warming attempt

Costs#

Warming requests are real provider requests. They can consume tokens, incur costs, count against rate limits, and fail like other model requests.

• Shorter intervals increase request volume.
• Longer durations allow more warming requests.
• Enable warming only when its provider-side benefit is worth the added usage.

For example, the defaults allow up to seven warming attempts during one uninterrupted 30-minute window: at minutes 4, 8, 12, 16, 20, 24, and 28.

Disabling#

Set warming to false to disable it explicitly. Omitting the field also leaves warming disabled.

{
  "warming": false,
}