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",
  },
}

Durations

interval and duration accept duration strings. Both must resolve to finite values greater than zero; 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,
}