learn-agents-from-opencode reads the OpenCode source and explains the modules

The premise is to read a real agent, not to build a toy one

The framing in the documentation is what makes this repository distinct from the many agent tutorials that walk through a toy implementation. OpenCode is described as an excellent open-source Coding Agent project with complete implementations of core concepts such as Agent, Tool, Permission, Skill, Session and Provider, and the repository documents the tutorials the author compiled while studying the OpenCode source code, aiming to help readers understand the engineering design of a real-world Agent project rather than building a toy example from scratch. The target audience is stated in three groups: users who have already used coding agents like Claude Code, Codex or OpenCode and want to understand their internal workings, developers looking to implement their own controllable Coding Agent or other types of Agents, and engineers with requirements for Agent permissions, tool calling, session management, prompt assembly and other modules. The third group is the one that tells you the register, since the requirements listed are the ones a team actually has to satisfy.

The tutorials were written with agent help, then reviewed by hand

One methodological note matters more than it first appears, and the documentation states it plainly. The tutorials were primarily generated with assistance from OpenCode, Claude Code and Codex, and have been manually reviewed. That is an unusual admission to make about one's own tutorial series, and it cuts both ways in a way worth thinking about. On the positive side, the subject matter is exactly the domain those three tools operate in, so a tool that has read a lot of agent code can point at real design decisions, and the manual review is the step that keeps it from being a paraphrase of the upstream project notes. On the cautious side, a reader who already trusts a tool's account of how agents work has to be careful about circularity, which is why the recommendation to read the tutorials alongside the OpenCode source code matters. The repository ships that source as a Git submodule so you can follow the tutorials alongside the actual implementation, and the note says the tutorials reference source files under `opencode/packages/opencode/src/...`.

Getting the source is two commands, and the submodule is the point

The setup exists to make the reading possible, and the recommended route is the recursive clone:

# Clone with submodule (recommended)
git clone --recursive https://github.com/yexia553/learn-agents-from-opencode.git

# Or if already cloned, initialize the submodule
git submodule update --init --recursive

# The OpenCode source will be available at ./opencode/
cd opencode && bun install

The last line is worth pausing on, because it tells you something about the project you are studying. The OpenCode source is a TypeScript project that installs with bun, so the tutorial repository expects you to have that runtime available if you intend to run the code rather than only read it. The alternative route, `git submodule update --init --recursive`, is for a checkout that already exists, and both are needed if you cloned without the recursive flag first. This is a small thing, but it is the shape of the whole project: the repository is a reading environment, and the source it explains is a real dependency of that environment rather than a copy pasted into it.

The index runs from the system prompt to the provider layer, in order

The tutorial index is a curriculum and the order is the argument. It starts with a learning plan, described as a complete architecture learning roadmap, and then walks the subsystems. Number 01 is the System Prompt, covering prompt construction, Provider adaptation and environment injection. Number 02 is the Permission System, covering permission rules, the request flow and BashArity. Number 03 is the Agent System, covering built-in Agents, the configuration system and permission integration. Number 04 is the Tool System, covering tool definition, registration and the execution flow. Number 05 is Iterative Info Gathering, covering tool chaining, the Explore Agent and SubAgent. Number 06 is the Skill System, covering skill definition, the discovery mechanism and tool integration. Number 07 is the Session System, covering session management, message flow and context compression. Number 08 is the Provider System, covering multi-model adaptation, SDK initialisation and cost calculation. The progression is not arbitrary. Prompt construction comes first because every later subsystem receives a prompt, permissions come before agents because an agent is defined partly by what it is allowed to do, and sessions come late because a session is where the accumulated state of the earlier layers lands.

BashArity and context compression are the two details worth a tutorial each

Two entries in the index reveal what the author thinks is actually hard about agent engineering, and neither is a fashionable topic. The permission chapter names BashArity specifically, alongside permission rules and the request flow, which suggests the model treats command approval as a structured problem about how many arguments a command needs rather than a simple allow or deny. The session chapter names context compression alongside session management and message flow, which is the other place where a real implementation has to make a hard choice, since a long conversation has to be summarised without losing the information the next turn needs. The skill chapter, covering skill definition, the discovery mechanism and tool integration, is the third that stands out, because skills are the unit that lets a user extend an agent without writing code, and the discovery mechanism is the part that a naive implementation gets wrong by scanning the wrong directory. The chapter list is therefore a list of the places where a self-built agent usually diverges from a production one.

The repository is a docs tree plus a submodule and the usual governance files

The structure tells you how little code there is. The documentation lives under `docs/`, with a `README.md` that acts as the full navigation index, a `00-learning-plan.md` file, and a `tutorials/` directory holding the eight numbered chapters. The OpenCode source sits alongside it as a submodule at `opencode/`, with its own `packages/` and `src/` tree, and the `opencode` entry in the top level listing is that submodule rather than a vendored copy. The rest is the standard set of community files: `.github/` with an issue template directory, workflows and a pull request template, plus `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`, `LICENSE` and both `README.md` and `README.zh.md`. There is an `.editorconfig`, a `.markdownlint.json` and a `.gitmodules`, which is the whole dependency story of the repository itself.

The English version exists, the tutorials do not

There is a language gap in this project and the documentation is direct about it. The tutorial documents below are currently available in Chinese only, and English translations will be added progressively. The repository does have a bilingual front page, with a link to the Chinese README and an English option, and the project description itself is written in Chinese as a tutorial series on learning agent development architecture from the OpenCode source code. For an English reader this creates an asymmetry worth naming. You can read the index, the structure, the setup and the audience in English, and the English translations are being produced over time, but the eight chapters that carry the actual teaching are Chinese documents today. That is a real constraint on who can use the series, and it is the sort of thing a prospective reader should check before planning a study schedule around it, rather than discovering it halfway through the permission chapter.

Where a tutorial series is the wrong answer

Two limits are worth naming. The first is that the tutorials explain one implementation rather than the field, and an implementation is a set of choices rather than a specification. If you read the permission chapter and then write your own permission system, you will have copied OpenCode's design, and OpenCode's design was made for its own agent loop, its own tool set and its own user expectations. The alternative to weigh against is the source of truth for each model provider, which is the API documentation for that provider, and for the tool-calling conventions themselves. The difference in approach is that this repository gives you a coherent narrative across subsystems, which the individual specifications do not, and that narrative is exactly what is missing when you try to assemble an agent from API docs alone. The second limit is that a reader is learning from a snapshot. The OpenCode source moves, the tutorials reference paths under `opencode/packages/opencode/src/...`, and a chapter can describe a file that no longer exists in the same shape. The alternative for a working implementation rather than a working understanding is to read the code of the agent you actually intend to run, which is what the repository is nudging you towards by shipping the submodule.

Editorial conclusion

learn-agents-from-opencode is worth working through if you are building your own coding agent and want one subsystem at a time against a real implementation, because the tutorials are ordered so that the permission system, the tool system and the session system build on each other, and because the OpenCode source is vendored as a submodule so the code being discussed is in the same tree. It is a poor fit if you cannot read Chinese, since the documentation states the tutorial documents are currently available in Chinese only with English translations to be added progressively, and a poor fit if you want a runnable framework rather than an explanation of one. Before you start, clone the repository with the recursive flag so the OpenCode source is present, and note that the last push to the repository was on 2026-04-30.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. yexia553/learn-agents-from-opencode on GitHub