Source Code Learning Path

This is a guided course through OpenCode’s source code. The 8 modules below are ordered bottom-up: start with the foundation (config, providers, permissions), move through integration (MCP, LSP), then the core engine (Agent), and finish with the user-facing interfaces (Command, CLI).

Each chapter is a deep dive (3000-4000 words) into one module’s architecture, types, core flow, and design tradeoffs. Read them in order for a complete mental model, or jump to the module you need.

Prerequisite skills

Before reading the source code, make sure you’re comfortable with:

Skill	Importance	Why
TypeScript	Essential	The codebase is fully typed; types are the primary documentation
Promises / async-await	Essential	Almost everything is async (LLM streaming, file I/O, tool execution)
Node.js streams	Important	LLM responses and session events are streamed
Git / terminal	Helpful	You’ll clone the repo and run it locally to debug
React / Vue	Not needed	The TUI is not a web framework; you don’t need frontend skills

Time expectations

Goal	Time	What you’ll be able to do
Understand one module	~30 min	Read one chapter and explain what that module does
Trace a full request	~1 week	Follow how a prompt flows from CLI → Session → Agent → Provider → Tool → response
Modify a feature	~1 month	Change a behavior (e.g., add a new permission rule) and have it work
Write an extension	1-3 months	Build a plugin, custom tool, or contribute to core

The 8 chapters (in order)

Foundation — the ground layer

Config · Beginner · ~25 min How configuration loads: 6-layer priority, Zod schema, JSONC parsing, hot reload. Start here — every other module depends on config.
Provider · Beginner · ~20 min The model abstraction layer: how OpenCode talks to 75+ LLMs via Vercel AI SDK without per-provider HTTP clients.
Permission · Intermediate · ~25 min The safety gate: three-tier decisions (allow/deny/ask), wildcard matching, cascading denial, batch approval.

Integration — external protocols

MCP · Intermediate · ~25 min The external tool channel: three transports, OAuth 2.0 + PKCE, how MCP tools become AI SDK dynamic tools.
LSP · Intermediate · ~25 min IDE-grade code understanding: Effect Service architecture, 30+ language server definitions, diagnostics.

Core — the engine

Agent · Advanced · ~30 min The configuration-vs-execution split: Agent is a config definition, Session drives the loop. Concurrency, error handling, state management.

Interface — what users touch

Command · Advanced · ~20 min Commands as config, not functions: four sources (built-in, config, MCP prompts, skills), template-driven execution.
CLI · Advanced · ~25 min The entry point: Yargs command tree, dual-mode design (TUI worker vs non-interactive run), SSE event bridge.

Where to start

If you’re new to the codebase: start with Config.

If you want to understand how a prompt becomes code edits: jump to Agent and follow its call chain backward.

If you want to extend OpenCode with a new tool: read MCP and Command.