OpenCode v2

OpenCode 2.x is the current mainline of the open source AI coding agent (material current as of v2.0.22, October 2026). The opencode binary is V2; opencode2 survives only as a legacy alias. V2 replaced the V1 server API, plugin system, and permission model, and reworked the internal architecture around an Effect-TS service core with a managed background service.

Overview

• Repo: github.com/anomalyco/opencode
• Install: curl -fsSL https://opencode.ai/install | bash or npm install -g opencode-ai
• Run: opencode in your project
• Runtime: Bun
• Language: TypeScript with Effect-TS
• Status: Stable mainline (2.0.22); plugin and server APIs still evolve between minors

Contents

• Architecture - Client-server topology, package structure, service lifecycle
• Concepts - Core mental models: sessions, agents, permissions, plugins
• Quickstart - Install, connect a provider, start coding
• How-To - Configure agents, permissions, MCP servers, plugins; read local session data (how-to/read-local-data.md: opencode.db schema, opencode api surfaces)
• Deep Dives - Effect service architecture, AI SDK abstraction, service lifecycle
• Walkthroughs - Request lifecycle, plugin hook chain
• Troubleshooting - Background service issues, common errors
• Notes - V1 to V2 migration reference, ecosystem

Resources

• OpenCode Docs - Official documentation
• Config Schema - JSON Schema for config validation
• Migration Guide - V1 to V2 migration
• Discord - Community