@opencode/theme

Highlights

• Clear Free-Limit Recovery: When your free messages run out, Desktop and the TUI now show the reset time, restore your submitted prompt, and offer direct upgrade or model-switching actions instead of a generic error. (#57466, #57467, #57471)

• Hide Free Models: Set OPENCODE_DISABLE_FREE_MODELS=1 or true to remove zero-cost models from OpenCode and OpenCode Go catalogs, defaults, and fallbacks.

• Configurable Location Unloading: Set experimental.location_idle_timeout to a duration such as "4 hours", or to false, to control when inactive location services unload.

• Reliable Fresh Installs: The installer now creates ~/.zshrc or Fish’s config.fish when missing, adds OpenCode to PATH, and tells you to run exec $SHELL.

Core

Improvements

• Added OPENCODE_DISABLE_FREE_MODELS for hiding free OpenCode and OpenCode Go models.

• Added experimental.location_idle_timeout, accepting a duration string or false.

Bug fixes

• Fixed fresh zsh and Fish installations not adding OpenCode to PATH when their configuration file did not exist.

• Kept locations loaded while sessions are waiting for input, running long tools, or owning background jobs.

• Fixed legacy console.opencode.ai credentials not being forwarded to opencode.ai/console.

• Reused recent Console configuration checks when inference is rejected, avoiding unnecessary repeated checks.

TUI

Improvements

• Added an inline free-limit notice with the reset time and /connect and /models actions, while restoring the submitted prompt when the composer is empty.

• Restored the animated “Free limit reached” OpenCode Go dialog with Subscribe, Dismiss, and Don’t show again actions.

Bug fixes

• Stopped showing redundant failure notifications when the free-message limit is reached.

• Only shows “location unavailable” when the server explicitly reports the location as missing.

Desktop

Bug fixes

• Restored the free-limit dialog, reset-time timeline notice, and submitted prompt after free usage is exhausted. Subscribing to OpenCode Go now updates the current session’s model instead of opening another draft.

SDK

Improvements

• Added retryAfterMs to structured session errors so clients can display provider-supplied retry timing.

Bug fixes

• Fixed retry timing being dropped from quota, rate-limit, and provider-internal session errors.

• Fixed OpenAI realtime client-secret requests by supplying the required expires_after.anchor.

Extensions

Bug fixes

• Fixed Code Mode async jobs interleaving in the middle of statements and losing writes, while preserving concurrent tool calls. Thanks @RhysSullivan!

Highlights

• Persistent Terminals on Windows: Windows users now get persistent PTYs through the same terminal workflow available on macOS and Linux.

• Todo Lists in the TUI: Enable { "experimental": { "todo": true } } to give models the todowrite tool and display their task list in the session and sidebar.

• Reliable Long-Running TUI Commands: Plugin commands, shell calls, and other TUI requests can now run beyond Bun’s five-minute fetch deadline without losing their connection.

Breaking changes

Version 2.1 makes intentional changes to public SDK, HTTP message/event, and plugin contracts so provider replay data and compaction use consistent names and shapes. Integrations must adopt the new fields. Existing stored sessions, credentials, and older session imports remain readable through compatibility decoders; no database migration is required.

Provider replay data is now native

Provider-owned replay data previously used different names on different surfaces. Read and write native instead; a tool's execution state and UI metadata are separate and are not renamed.

Tool call and result data share tool.native

Tool parts no longer have separate providerState and providerResultState fields:

 tool
-  providerState?
-  providerResultState?
+  native?
   state

Success and failure events shallow-merge their native into the call's existing native. Missing result data preserves call data; result values win on duplicate keys. Provider/protocol implementations must use distinct keys when call and result values differ. There is no state.native, resultNative, or nested { call, result } envelope.

Replay passes the merged blob to the protocol, which reads the fields it needs. Tool calls receive it only for the same provider and model. Provider-run results receive it for the same provider, including after a model switch. Local results receive it only for the same provider and model when the step did not fail. Legacy stored or imported providerResultState is merged into tool.native when read. Execution status and readable output remain in tool.state.

Key credential setup answers move to metadata

Credential.Key.configuration is removed. Public credential writes must put setup-form answers in the existing metadata field:

 { type: "key", key: "...",
-  configuration: { account: "example" }
+  metadata: { account: "example" }
 }

Existing stored credentials and opencode auth import still accept the old shape. Legacy configuration is merged into metadata; the legacy configuration value wins when both contain the same key. This compatibility is for storage/import, not a reason to keep sending configuration in public writes.

Summary compactions reference kept messages

Compaction messages and session.compaction.started / session.compaction.ended no longer expose recent. New summary compactions reference the first message retained verbatim through metadata.keepID instead of storing a second, flattened copy:

 summary compaction
-  recent: "[User]: ... [Assistant]: ..."
+  metadata: { keepID: "msg_..." }

History reconstructs the kept text from that message up to the compaction boundary. Forks remap the reference to their copied messages, and compaction hooks can override keepID through metadata. Kept text from pre-2.1 compactions and V1 imports remains available as metadata.recent. New compactions store the reference, not the duplicated text.

Provider compaction windows move to native.messages

Completed compactions and session.compaction.ended no longer have providerContext. The replacement message window now lives in native.messages:

-  providerContext: { version, provenance, messages }
+  native: { messages }

Native compaction replay now matches the compaction's provider ID and model ID, rather than route/protocol/endpoint provenance. If they do not match, history uses the original messages. Endpoint changes alone no longer block replay, and request hooks that rewrite the base URL no longer block native compaction or replay.

Summary compactions no longer save the summary call's unused provider data in native. A compaction hook's result.native is still stored; if it contains messages, that window is replayed instead of the summary. Old providerContext rows and events are converted when read, including the media format used before 2.0.15.

Remove the unused session.compacted event

The transitional session.compacted event is removed from the public event surface. Update event subscriptions and schema imports to use the current compaction lifecycle events, including session.compaction.started and session.compaction.ended.

Core

Improvements

• Added persistent PTY support for Windows x64 and ARM64.

• Restored the todowrite tool behind { "experimental": { "todo": true } }; it accepts the complete list as { todos: [{ content, status }] }.

• Restored session archiving, including archive-state filtering and restoring archived sessions.

• Added support for editing saved permission actions and resource patterns.

• Summary compaction now covers the whole conversation while retaining recent text verbatim, and begins earlier by default to leave more response room.

• Added the streamUsage model compatibility option for providers that reject stream_options.

Bug fixes

• Prevented long-running TUI, run, and mini requests from hitting Bun’s default fetch deadline. Thanks @Finn763.

• Retried broken-pipe transport failures. Thanks @sdivyanshu90.

• Retried transient failures from buffered model generations instead of immediately failing.

• Ignored provider keep-alives and unknown stream events while continuing to reject malformed known events. (#56286, #56669)

• Limited the OpenAI-compatible store field to OpenAI, Azure, and providers that explicitly opt in.

• Preserved more complete context during compaction and stabilized image trimming and instruction baselines to improve prompt-cache reuse. Thanks @rrauenza for the revert fix. (#56983, #54410)

• Ensured shell completion is reported only after output capture finishes, and reported removed running shells as killed. (#56321, #56982)

• Prevented undefined permission metadata from breaking pending-request responses.

• Bounded skill discovery and file watches, and tolerated filesystem permission denials during sandboxed startup. (#55597, #55817)

• Included the root script/ directory in Nix CLI builds.

TUI

Improvements

• Added todo lists to session output, compact cards, and the sidebar when experimental todo support is enabled.

• /models now opens on the current model and preserves the server’s preferred model order.

• Added visible keyboard focus and reverse Shift+Tab navigation to export options.

Bug fixes

• Kept long-running commands connected beyond Bun’s fetch deadline and restored the composer with an error toast when an existing-session shell command fails. Thanks @Finn763.

• Retried session.wait after transport interruptions in mini.

• Highlighted the selected file in the diff tree. Thanks @Tarquinen.

• Removed per-row resize listeners from selection dialogs. Thanks @tobwen.

• Corrected spacing above simple-dialog footers.

• Fixed Mermaid flowchart rendering in the TUI when labels contain apostrophes.

Desktop

Bug fixes

• Show free OpenCode models alongside their paid counterparts by default instead of hiding them when they share the same model family and release date.

SDK

Improvements

• Extended the existing experimental server voice API, client.voice.session(...), with Gemini Live support for gemini-3.8-live* models over WebSocket. The server uses a stored Google key or GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_API_KEY.

• Added client.permission.saved.update(...) for changing a saved permission’s action or resource.

• Added archive filtering to client.session.list(...) and archive updates to client.session.update(...).

• Added idle to the supported client.message.list(...) type filter.

Extensions

Improvements

• Added paginated ctx.session.list(...) to both Effect and Promise plugin APIs.

Highlights

• Copy the Latest Reply: Run /copy in the TUI to copy the latest assistant message or completed compaction summary instead of the full transcript. (#56053, #56055)

• Auth Login in Headless Environments: opencode auth login no longer crashes in a container or other headless environment that cannot open a browser; use the URL already printed in the terminal to continue.

Core

Bug fixes

• Prevented opencode auth login from crashing when no browser opener such as xdg-open is available.

• Gemini sessions now retry or continue after intermittent MALFORMED_RESPONSE finishes instead of immediately failing.

• Made snapshot capture resilient to concurrent Git object writes on Windows.

TUI

Improvements

• Changed /copy to copy the latest assistant message; the full transcript remains available from the command palette or /export.

Bug fixes

• /copy now copies a completed compaction summary when it is the latest response.

SDK

Improvements

• Added the experimental client.voice.session(...) API for server-brokered OpenAI GPT-Live and Realtime WebRTC sessions, OpenAI Realtime WebSocket sessions, and xAI Grok Voice WebSocket sessions. It uses an API key stored on the server or OPENAI_API_KEY/XAI_API_KEY; ChatGPT sign-in credentials are not used.