Migrating to OpenCode 2.0

This documents how to move from OpenCode v1 to OpenCode v2, describing compatibility, intentional breaking changes, and concrete config transformations so users can migrate with minimal disruption. Three breaking changes require attention: a new plugin API, revised server/client contracts, and consolidation of terminal client configuration into a single global cli.json (auto-migrated). Most V1 behavior is preserved: V2 reads the same config locations, normalizes supported V1 fields in memory, and can auto-convert files on request while preserving unrelated settings. A practical migration path is provided: keep existing files, start V2 to validate models/credentials/agents/permissions, port plugins and API integrations, then convert configs to native V2 shapes when ready. Keep a V1 copy during validation because both use the same file locations.

Configuration differences are enumerated precisely so users can update keys and shapes: permission rules become an ordered array with renamed actions (bash→shell, task→subagent, write/patch→edit); singletons like agent/command/reference/attachment/snapshot become pluralized; agent prompt→system, variant joins model with “#”, and temperature/top_p move under request.body; MCP servers group under mcp.servers, enabled→disabled and split timeout purposes; compaction uses keep.tokens and buffer; skills combine paths and URLs into one array; providers separate package, settings and gain an aisdk: prefix for AI SDK packages; models use modelID, explicit capabilities, and variants become arrays. Unsupported legacy fields are preserved or warned about; reach out to troubleshooting for compatibility bugs.