learn-agent: a 20-chapter TypeScript tutorial that builds an AI Agent harness from scratch

What learn-agent solves, and who it is written for

Most agent tutorials stop at calling a model API once. This repository starts from the opposite premise: the model reasons, and the harness is what turns a decision into a safe action in a real environment. The README frames the whole course around four questions, how an agent acts, how it is constrained, how it handles long tasks, and how several agents collaborate and reach outside tools. Each of the 20 chapters answers one of them and adds one main capability.

The audience is an engineer who already writes TypeScript and wants to see how permissions, hooks, memory, task graphs, worktrees and MCP fit together in one runtime. The teaching rule is explicit: every chapter keeps the behaviour of the previous one, and chapter 20 does not invent a second loop. It verifies that the first 19 chapters can cooperate inside the same AgentRunner. That constraint is what makes the material different from a pile of isolated demos, and it is also what makes it long.

The chapter ladder: one mechanism per snapshot

The progression is concrete. Chapters 1 to 4 cover the loop, the tool registry with Zod input validation and workspace-safe paths, a four-state permission policy with approval and audit, and four hook lifecycle points named UserPromptSubmit, PreToolUse, PostToolUse and Stop. Chapters 5 to 10 move into planning with a todo snapshot, subagents that share the run boundary but cannot delegate recursively, a skill system that scans summaries first and loads bodies by name, artifact spooling with layered compaction, cross-session file memory, and a dynamic prompt provider that assembles the runtime system prompt in a fixed order.

Chapters 11 to 14 handle reliability and scheduling: truncation, oversized input, 429 and 529 responses, Retry-After, fallback models, cancellation and a total deadline, then a task DAG persisted as atomic JSON with owner checks, then background jobs that write to disk before starting a worker, then a cron scheduler with timezone calculation, UTC persistence and durable versus session-only lifetimes. Chapters 15 to 18 add persistent teammates with a FIFO mailbox, a collaboration protocol with plan approval and deterministic shutdown, SQLite-backed atomic task claiming with leases, and Git worktree isolation for parallel development. Chapters 19 and 20 close with an MCP tool pool behind an allowlist and the assembled harness.

Installing learn-agent and running your first chapter

The README targets Windows 11 with PowerShell commands and requires Node.js 20.12 or newer. Everything lives under code/, so the first step is to install dependencies there.

Set-Location '.\code'
npm ci

Running against a real model needs a .env file in code/. The README says to copy the template and fill in four variables.

if (-not (Test-Path '.env')) {
  Copy-Item '.env.example' '.env'
}

The four keys are OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL and OPENAI_FALLBACK_MODEL. Without credentials the README says to run tests, type checks and the build instead, because the offline tests inject the model and other external boundaries and need neither a key nor a network.

Each chapter has a fixed npm script. Chapter 1 takes a prompt and runs the minimal loop.

npm run ch01 -- --prompt "列出当前目录"

There is also a unified entry point that selects the chapter by number, useful when you want to jump to the task DAG material without reading the earlier scripts.

npm run agent-tutorial -- run --chapter 12 --prompt "建立 schema、endpoints、tests 和 docs 的任务依赖"

The README gives a baseline for the current code: npm test covers 65 test files and 429 tests, and typecheck, lint, format:check, build and verify:snapshot-drift all pass. Treat that as a claim from the repository, not as something reproduced here.

Verifying a chapter instead of trusting the file listing

The README is unusually direct about this: do not treat a file existing or importing successfully as proof that a chapter is complete. The verification commands run from code/.

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

The guidance is to run the matching test:chNN and typecheck for a single chapter review, and to run the full set after shared runtime changes. The verify:snapshot-drift script is the interesting one, because the snapshots are supposed to accumulate rather than diverge, so drift between chapters is treated as a defect. From chapter 15 onward the CLI wires both teammate and cron wakeups into the same runEvents() entry point of AgentRunner, and the README notes that entry regression tests exist to stop that wiring from degrading.

Where learn-agent is the wrong tool

This is a course, not a package. There is no published library to import, no API stability promise, and no release history in the repository. If you need an agent framework to ship next month, the 20-chapter structure works against you: you would have to read the permission model, the hook lifecycle and the compaction strategy before you have anything running.

The code also assumes the OpenAI-compatible interface, with OPENAI_BASE_URL and an optional fallback model. Nothing in the README describes adapters for other providers, so a team standardised on a different API shape would be adapting the examples themselves. The offline tests deliberately inject the model boundary, which is good for reproducibility but means the test suite does not exercise a real provider; the README explicitly says the real-model smoke test is not part of the offline gate. Finally, the README does not document rollback, versioning or a migration path between chapter snapshots, so you cannot treat a snapshot as a maintained branch.

How it differs from ai-agent-book and learn-claude-code

The README names two reference projects and is clear that the code, chapter numbering, TypeScript implementation and acceptance criteria belong to this repository, not to them. bojieli/ai-agent-book is a 10-chapter book built on the line that an agent equals an LLM plus context plus tools, with a broad view of principles, memory and multi-agent work. shareAI-lab/learn-claude-code is a progressive tutorial that builds a Claude Code style harness and keeps tools, knowledge, observation, action interfaces, permissions and a single agent loop inside one harness view.

The difference here is the combination. learn-agent takes the incremental teaching method, one mechanism per lesson and a final reintegration, and reimplements it in TypeScript with strict contracts and a test gate that includes snapshot drift checking. It also goes further into operational ground than either reference summary suggests: SQLite claim transactions with leases, Git worktree reservation and claim routing, and an MCP allowlist feeding a dynamic registry snapshot. If you want the conceptual sweep, ai-agent-book is wider. If you want harness internals in one pass, learn-claude-code is more compact. This one is the longest and the most test-bound.

Maintenance, licence and the cost of keeping up

The repository is not archived and the last push was on 2026-09-02, which is recent, so the material reflects a current codebase. There are no releases in the repository, which fits a tutorial whose unit of change is the chapter snapshot rather than a version tag.

The upgrade cost sits in the snapshots. Because each chapter keeps earlier behaviour and the combination root accumulates P01 to P20 profiles, a change to a shared runtime can touch many chapters at once, which is exactly why verify:snapshot-drift exists and why the README asks for the full suite after shared changes. Budget for that whenever you pull.

On licensing, the README says the articles and code follow the declarations in the repository's actual files, and no licence identifier appears in the repository listing. There is no LICENSE file in the top-level entries. If you plan to reuse the code, read those file-level declarations yourself; nothing in the README grants rights, and this article gives no legal advice.

Editorial conclusion

Adopt learn-agent if you want to read and run one mechanism at a time inside a TypeScript codebase and check each chapter with its own tests. Do not adopt it as a dependency you import into a product; it is a tutorial whose snapshots live under code/chapters, and the README treats the current source and tests, not file presence, as the proof of completion. Before committing time, check the licence statements in the repository files, since the README defers to them, and run npm ci, npm run typecheck and npm run test:ch01 in code/ to confirm the toolchain works on your machine.

Frequently asked questions

Official sources

1. Issues
2. README
3. ryzqi/learn-agent on GitHub