OpenCode Support Release Notes

Status: ready for the OpenCode support release
Last checked against OpenCode docs: 2026-05-28
Support level delivered: PTY/TUI-first OpenCode support for desktop macOS/Linux. Windows support is WSL-first and still planned.

User-Facing Release Note

Coldtea now supports OpenCode as a native terminal agent. If opencode is installed in your normal shell, Coldtea can discover it, launch the OpenCode TUI in the selected project or worktree, preserve OpenCode's own setup and permission prompts, and show OpenCode sessions in the same workspace flow as other CLI agents.

This release keeps OpenCode in charge of provider setup. Use OpenCode's /connect flow in the TUI or opencode auth login from a shell pane. Coldtea does not collect, store, read, or sync OpenCode provider API keys.

See the official OpenCode docs for the OpenCode-owned pieces:

Setup And Onboarding

Install OpenCode using the current command from the official install docs.
Confirm opencode works in a normal terminal.
Restart Coldtea so agent discovery can refresh.
Launch OpenCode from the agent picker, terminal empty state, or task flow.
If OpenCode asks for a provider, complete setup inside OpenCode with /connect or run opencode auth login in a shell pane.

Coldtea launches the native TUI as bare opencode by default. Explicit OpenCode default args configured in Agent Settings are appended after the program. Saved-session actions use OpenCode's TUI continuation flags:

opencode [user default args...] --session <session-id>
opencode [user default args...] --session <session-id> --fork

What Coldtea Adds

OpenCode discovery from the user's login shell, process PATH, and common package-manager locations.
Native PTY launch in the selected project or worktree.
User-configurable OpenCode default args without changing the bare default.
Saved-session list, resume, fork, and delete flows scoped to the selected project/worktree.
A Coldtea-managed OpenCode plugin for lifecycle and permission side-channel events.
Session-scoped Coldtea MCP and startup prompt attachment through OPENCODE_CONFIG_CONTENT using {env:...} placeholders instead of durable tokens or prompt text.

Developer implementation notes remain in the repository docs for maintainers.

Known Limitations And Deferred Work

SDK, server, web, and ACP integrations are not default OpenCode support. They remain deferred optional side channels pending explicit security and UX review. See the official server, SDK, and ACP docs for those OpenCode surfaces.
Coldtea does not manage OpenCode provider credentials, custom provider forms, subscriptions, billing, or model availability.
Native Windows OpenCode launch is not part of this support level. The planned Windows path is WSL-first; see OpenCode Windows and WSL support.
OpenCode export/import/revert are not current Coldtea UI actions.
OpenCode has no current automatic implementation-plan artifact hook matching Claude's plan-acceptance hook, so OpenCode plans should be logged manually when they need to be attached to a Coldtea task.

Troubleshooting Notes

Use Troubleshooting and FAQ for user-facing recovery. The short version:

If OpenCode is missing, verify command -v opencode in a normal shell and restart Coldtea.
If auth or provider setup fails, use /connect, opencode auth login, OpenCode config, or provider environment variables. Do not paste provider keys into Coldtea settings.
If Coldtea's OpenCode side channels are missing, inspect the Coldtea dev app log for [coldtea:agents], [coldtea:terminal], [coldtea:local_api], and [coldtea:lifecycle], then inspect the pane output for wrapper diagnostics.
OpenCode config usually lives in ~/.config/opencode/opencode.json, project opencode.json / opencode.jsonc, and .opencode/. OpenCode auth is stored under ~/.local/share/opencode/auth.json; treat it as sensitive and do not copy its contents into support notes.

QA Evidence Summary

Documentation and implementation evidence to attach to a release review:

Official OpenCode docs were checked on 2026-05-28 for install, CLI, config, plugins, MCP, server, SDK, and ACP behavior.
Manual QA coverage includes install, first launch, auth, config preservation, MCP, lifecycle, saved sessions, worktrees, negative cases, and Claude/Codex/Gemini regressions.
Automated coverage exists around OpenCode agent detection/labeling, launch presets, saved-session resume/fork/delete behavior, wrapper config preservation, inline MCP config generation, plugin event forwarding, and notification hook session attribution.
This docs-only task does not claim a fresh manual end-to-end pass. For a release sign-off, copy the run record from docs/QA_OPENCODE.md and attach screenshots/log excerpts for the exact Coldtea build and OpenCode version.