Model or dataset
ryzqi/learn-agent avatar
ryzqi/learn-agent

learn-agent builds an agent harness one capability per chapter, without replacing the loop

A 20-chapter hands-on Chinese tutorial on AI agent architecture, with runnable TypeScript code, covering tools, permissions, memory, multi-agent setups, worktrees, and MCP.

421 stars78 forksTypeScriptLicense varies

At a glance

What is it?
A 20 chapter Chinese tutorial with runnable TypeScript snapshots, where each chapter adds exactly one mechanism and chapter 20 exists to prove the previous nineteen coexist inside a single AgentRunner.
Who is it for?
Work through learn-agent if you want to see permission policy, hook lifecycles, context compaction and multi-agent claiming built as separate modules you can read in order, and if you are willing to work in Chinese and follow PowerShell examples on Windows. It does not fit someone who wants a library to depend on: there are no releases, no licence file, and the value is in the sequence rather than the final harness.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 74 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ryzqi/learn-agent421 ★ · +78
Star history
Repository2026-09-172026-11-15
ryzqi/learn-agent343421

78 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One capability per chapter, and chapter 20 refuses a new loop

The stated rule of the tutorial is that each chapter adds a single main capability while everything from earlier chapters keeps working, and that the final chapter does not invent a second agent loop. Its job is to check whether the previous nineteen mechanisms still cooperate inside one `AgentRunner`. That is an unusual constraint for a tutorial, and it is the reason the course holds together as one system rather than twenty demos.

Around that rule sit four questions the chapters advance in order: how the agent acts, which is a loop that reads a model reply, executes a tool and appends the result; how the agent is constrained through file boundaries, permission policy, hooks and a structured protocol; how long work is extended with a TODO list, sub-agents, skills, context compaction, memory, recovery, background tasks and Cron; and how several agents cooperate and reach external capability through claiming, a mailbox, protocol approval, SQLite, worktrees and MCP.

Layout follows the same logic. Articles sit at the repository root, one Markdown file per chapter, and `code/chapters/chNN/` holds that chapter's `src/` plus cumulative `tests/`. Later snapshots keep earlier behaviour and add capabilities at the composition root according to a `P01` to `P20` profile.

Permission and hooks arrive before memory does

Chapters 2 to 4 are where safety gets built, and they come before anything about recall. Chapter 2 adds a `tool_registry` and `files`, with Zod validating tool input and workspace paths constrained so a tool cannot write outside the workspace. Chapter 3 adds `policy`: approval, auditing, a four-state permission decision and one shared error boundary for tool failures. Chapter 4 adds `hooks` at four lifecycle points named `UserPromptSubmit`, `PreToolUse`, `PostToolUse` and `Stop`.

Two of those chapter titles say outright that they replicate Claude Code's permission system and hook decoupling, and the repository is candid about borrowing: the reference section credits `shareAI-lab/learn-claude-code` for the teaching method of adding one mechanism per lesson and re-integrating at the end, and `bojieli/ai-agent-book` for the principle-first framing with evaluation defined before implementation.

What the project claims for itself is the TypeScript implementation, the chapter numbering and the acceptance criteria, explicitly not an official translation or a chapter-by-chapter copy. Whether that separation holds is worth checking against the two upstream projects if you already know them.

Context is treated as a budget with five separate mechanisms

Chapters 5 to 10 all attack the same problem from different angles, which is the clearest sign that the author treats context as an engineering budget rather than a prompt-length concern. `todo` keeps a full plan snapshot with state validation and a reminder when the plan has gone stale, so a long task does not drift. `subagent` runs delegation with isolated history, a shared runtime boundary, recursive delegation forbidden and a turn limit. `skills` scans summaries first and loads a body only when the name matches, so knowledge enters context on demand instead of by stuffing.

Then `artifacts` and `compaction` write results to disk, trim in layers and restore from a summary when the budget runs out, and `memory` extracts from the canonical history, organises it and retrieves it across sessions. Chapter 10 adds `dynamic_prompt`, a provider that assembles the runtime system prompt in a fixed order so that assembling context does not become a second copy of the loop.

Five mechanisms for one problem is also five places to look when something goes wrong, and the chapter titles frame the motivation as amnesia under a Transformer rather than as a token limit.

Failure handling is a module with an owner check

Chapter 11 puts resilience in one place called `recovery`, covering truncation, oversized input, 429 and 529 responses, `Retry-After`, fallback, cancellation and an overall deadline. Treating the deadline as part of the module rather than the caller's problem is the part worth copying.

The task system follows. `task_dag_json` holds dependencies, persists state atomically as JSON, validates the DAG and checks the owner field so a task cannot be claimed under a forged identity. `background` persists to disk before starting a worker, joining the async job to the conversation through a placeholder result and a completion event, which is what keeps a half-finished job from looking finished. `cron` computes time zones, persists in UTC, distinguishes a durable schedule from a session-only one, and triggers through an outbox.

Taken together these four chapters are the difference between an agent that fails visibly and one that stalls quietly, and they are the part of the tutorial with the least appeal to fashion.

Agents claim work in SQLite and edit in separate worktrees

The collaboration chapters start with message delivery and end with file-level isolation. `teammate` and `mailbox` give a persistent teammate, FIFO messages, recovery, bad-message isolation and Inbox injection. `protocol` and `plan_gate` require registering before sending, demand a complete matching response, gate plans on approval and shut down deterministically. Then `task_dag_sqlite` with `work_stealing` moves claiming into a transaction with leases and token history, trimming the tool set each role may call. Chapter 18 adds `worktree`: reserve a tree, bind a claim to it, route execution context into it, and clean up through an explicit `needs_review` boundary.

Worktrees are the chapter that answers a question the others leave open. Once several agents edit one repository, file conflicts stop being a coordination problem and become a filesystem decision.

One wiring detail matters if you read the source. From chapter 15 the CLI feeds both teammate messages and Cron wakeups into the same `AgentRunner` through its `runEvents()` entry, and entry regression tests guard that wiring from decaying.

Running a chapter from PowerShell on Windows

Examples are written for Windows 11 in PowerShell, and Node.js `>=20.12` is the stated requirement. Dependencies install from the `code/` directory:

powershell
Set-Location '.\code'
npm ci

A real model run needs `.env`, and the tutorial is explicit that offline work does not. With no credentials it tells you to run tests, type checking and the build rather than treating a live OpenAI smoke test as a required gate.

text
OPENAI_BASE_URL=
OPENAI_API_KEY=
OPENAI_MODEL=
OPENAI_FALLBACK_MODEL=

Each chapter has its own script, and there is a unified entry point that takes a chapter number:

powershell
npm run ch01 -- --prompt "列出当前目录"
npm run ch20 -- --prompt "验证完整 Harness 的动态上下文、MCP 边界和资源关闭"
powershell
npm run agent-tutorial -- run --chapter 12 --prompt "建立 schema、endpoints、tests 和 docs 的任务依赖"

Run one chapter before reading the next, then compare: the exercise is to find what was added and why it could not be folded back into an earlier module.

The gate is a snapshot drift check, and the baseline is 429 tests

Verification is a script list, and the README states what passing currently looks like: `npm test` covers 65 test files and 429 tests, and type checking, lint, format check, build and the snapshot drift check all pass on the current baseline, verified serially.

powershell
npm run typecheck
npm run test:ch01
npm run test:ch20
npm test
npm run lint
npm run format:check
npm run build
npm run verify:snapshot-drift

`verify:snapshot-drift` is the one that encodes the tutorial's central rule in tooling: if a later chapter quietly changes behaviour that an earlier chapter established, this is what notices. Per-chapter review is expected to run the matching `test:chNN` plus type checking, and only direct verification counts as passing.

Two things to weigh before committing time. The repository has no GitHub releases, so there is no version to pin and nothing to upgrade to, and the licence section defers to whatever the repository files declare while no licence file appears among the top-level entries. The last push was on 2026-09-02, and the only discussion venue offered is a forum link with community rules left to that forum.

Editorial conclusion

Work through learn-agent if you want to see permission policy, hook lifecycles, context compaction and multi-agent claiming built as separate modules you can read in order, and if you are willing to work in Chinese and follow PowerShell examples on Windows. It does not fit someone who wants a library to depend on: there are no releases, no licence file, and the value is in the sequence rather than the final harness. Verify first that the chapter you actually need is a module in the snapshot you can read, then run npm test and npm run verify:snapshot-drift before changing anything.

Frequently asked questions

What does ryzqi/learn-agent teach?

A 20 chapter Chinese tutorial that builds an agent harness in TypeScript, one capability per chapter: the loop, tools and file boundaries, permission policy, hooks, planning, sub-agents, skills, context compaction, memory, API recovery, task DAGs, background jobs, Cron, multi-agent coordination, SQLite claiming, worktrees, MCP and a final combined harness.

Do I need an API key to follow learn-agent?

No for the offline path. Tests inject the model and other external boundaries and require neither credentials nor network, and the project asks you to run tests, type checking and the build instead of a live smoke test. A real model run needs four values in `.env`: `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL` and `OPENAI_FALLBACK_MODEL`.

How do I run a single chapter of learn-agent?

From `code/`, each chapter has its own script, so `npm run ch01 -- --prompt "..."` runs the first one. A unified entry point takes a chapter number instead, as in `npm run agent-tutorial -- run --chapter 12 --prompt "..."`.

How does learn-agent verify that a chapter is finished?

By direct verification rather than by the file existing or importing: the matching `test:chNN` script plus `npm run typecheck`, and for shared runtime changes the full list ending in `npm run verify:snapshot-drift`, which is meant to catch a later chapter altering behaviour an earlier one established.

Does learn-agent solve file conflicts between parallel agents?

Chapter 18 adds a `worktree` module that reserves a Git worktree, binds a task claim to it, routes execution context into it and cleans up through an explicit `needs_review` boundary, so concurrent agents edit separate trees instead of the same files.

Official sources

  1. Issues
  2. README
  3. ryzqi/learn-agent on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ryzqi-learn-agent.svg)](https://hysenlabs.com/projects/ryzqi-learn-agent)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ryzqi-learn-agent.svg)](https://hysenlabs.com/projects/ryzqi-learn-agent)

Was this useful?