sanbuphy/learn-coding-agent: a reading pack for Claude Code's architecture

What problem sanbuphy/learn-coding-agent solves, and for whom

Reading the source of a large CLI agent is slow. The README's Stats table puts the codebase it studies at roughly 1,884 .ts and .tsx files and about 512,664 lines, with a single file, query.ts, at roughly 785KB. That is not something a developer absorbs in an afternoon, and it is not something the vendor documents at the level of internal structure. This repository exists to compress that reading into reports. It is a learning and research repository, in the README's own words, with material "compiled entirely from publicly available online references and discussions." The intended reader is a developer who wants to understand agent architecture, not someone shopping for a tool. The README states the intention is "to help developers better understand and utilize Agent technologies." Note the scope: the subject is claude-code specifically, and the reports are dated to Claude Code v2.1.88. If you are building your own agent and want to know how a mature one handles permissions, compaction or sub-agents, that is the audience this fits.

The five analysis reports and what each one covers

The substance lives in docs/, split into en/, ja/, ko/ and zh/ with five reports per language, so twenty files covering the same five topics. Report 01 is telemetry and privacy: two analytics sinks (first-party and Datadog), an environment fingerprint, process metrics and a repo hash attached to every event, and the finding that there is no UI-exposed opt-out for first-party logging, with OTEL_LOG_TOOL_DETAILS=1 enabling full tool input capture. Report 02 covers hidden features and codenames: animal names (Capybara v8, Tengu, Fennec, Numbat), feature flags built from random word pairs such as tengu_frond_boric, and hidden commands including /btw and /stickers. Report 03 is undercover mode, where the README says official employees auto-enter a mode that strips AI attribution from commits, with no force-OFF. Report 04 is remote control: hourly polling of /api/claude_code/settings, a blocking dialog on dangerous changes where rejecting exits the app, and killswitches for bypass permissions, fast mode, voice mode and the analytics sink. Report 05 is the roadmap: Numbat, KAIROS as an autonomous mode with tick heartbeats, voice mode gated but ready, and 17 unreleased tools. Each report is a claim about a specific build, and the README anchors them to v2.1.88. That anchoring is the useful part. It also means the reports age the moment the product moves.

The agent loop the README draws, and the harness around it

The clearest structural contribution is a short diagram labelled THE CORE LOOP. It shows messages going to the API, a check on whether stop_reason equals tool_use, and two branches: execute tools, append tool_result and loop back, or return text. The README then makes the point that matters for anyone building their own: "That is the minimal agent loop. Claude Code wraps this loop with a production-grade harness: permissions, streaming, concurrency, compaction, sub-agents, persistence, and MCP." The README also names a 12-part breakdown, "The 12 Progressive Harness Mechanisms," described as how Claude Code layers production features on the agent loop, and gives an Architecture Overview path of Entry, then Query Engine, then Tools/Services/State. A Tool System section is listed as covering 40+ tools, the permission flow and sub-agents, and the Stats table separately counts ~40+ built-in tools and ~80+ slash commands. The runtime note is that the project runs on Bun, compiled to a Node.js >= 18 bundle, with ~192 packages under node_modules. The directory reference names main.tsx as the REPL bootstrap at 4,683 lines, QueryEngine.ts as the SDK and headless query lifecycle engine, and query.ts as the main agent loop. Be aware that the README text supplied here is truncated mid-tree, so the directory reference should be read in the repository itself rather than from a summary.

How to start reading it: no install, just the docs tree

There is no package to install and no CLI to run, so the first step is fetching the repository and listing what it ships. The top level holds README.md, README_CN.md, README_JA.md, README_KR.md and docs/.

git clone https://github.com/sanbuphy/learn-coding-agent.git
cd learn-coding-agent
ls docs/

That gives you the four language directories. The README's Language line links the translations, so pick yours and go straight into it. Inside a language directory the README's own tree lists five Markdown files, for example under docs/en/: 01-telemetry-and-privacy.md, 02-hidden-features-and-codenames.md, 03-undercover-mode.md, 04-remote-control-and-killswitches.md and 05-future-roadmap.md. The README says to click any filename in the tree to jump to the full report. A sensible first real use is to read report 01 against your own threat model, then report 04, because those two describe behaviour that affects anyone running the tool in a managed environment. The README's summary table is the fastest way to decide which report to open: it lists a topic and key findings per row, so you can skip three of the five if they are not your concern. The only configuration value the README names in this area is OTEL_LOG_TOOL_DETAILS=1, which it says enables full tool input capture. That is a setting of the studied tool, not of this repository, so do not go looking for a config file here.

Where this repository is the wrong tool

Three limits are visible from the README alone, and they are worth stating plainly. First, it is not software. There is nothing to import, no API, no release. If you arrived hoping for a coding agent you can point at your repository, or a scaffold to build one, this is the wrong repository, and the RELATED SEARCHES phrasing around building an agent from scratch does not describe what is here. Second, the material is secondary. The README says it is compiled from publicly available online references and community discussions, which means the reports are not first-hand source analysis and the findings should be checked against the build you actually run. Third, the version anchor is narrow: the reports target Claude Code v2.1.88, and the roadmap report describes unreleased tools and codenames, which is exactly the kind of material that goes stale fastest. The licence situation compounds this. The repository states no licence, and the README instead carries a disclaimer that commercial use is strictly prohibited and that content will be removed on request from a rights holder. For an engineer deciding whether to adopt something, that is a hard boundary, not a formality. If your use is commercial, this is not the source to build on.

A real alternative: reading the agent loop in code you can run

The closest alternative is to build the minimal loop yourself in a small repository and grow it, which is the approach the phrase "coding agent from scratch" describes. The difference in approach is stark. This repository gives you a description of a harness at a scale you cannot reproduce: ~512,664 lines, a 785KB query.ts, 40+ tools, 80+ slash commands. A from-scratch implementation gives you a few hundred lines you fully understand, and nothing about permissions, compaction, sub-agents or MCP until you add them. Neither replaces the other. The reports are better at showing what the hard parts look like at production scale, because they name specific mechanisms such as hourly settings polling and killswitches. A from-scratch loop is better at teaching you why those mechanisms exist, because you hit the failure that motivates each one. If you want the conceptual grounding first and the production picture second, read the README's core loop diagram and the 12 harness mechanisms section here, then write the loop yourself and come back to the reports when you need to know how a mature implementation handled a specific problem.

Maintenance, licence and what to verify before relying on it

The repository is not archived, and the last push was on 2026-04-01. That is roughly five and a half months before today, so it is recent enough that the project has not gone quiet, but it is not a repository with a steady stream of commits either, and the README's promise to "continue to share more insights and practical discussions" is a statement of intent rather than a schedule. There are no releases, which fits a documentation-only repository: versioning happens through commits to Markdown files, so an upgrade is a git pull and a re-read, with no migration path to worry about. The cost is not maintenance, it is re-verification, because the reports describe a product that ships on its own cadence. On licensing, the README states no licence and instead imposes a restriction: commercial use is strictly prohibited, and the repository will remove content on request from a rights holder. That combination means you should not assume an open source grant of rights, and if you need to redistribute or use the material at work, that is a question for your own legal counsel rather than something the repository answers. Verify the version anchor first, then the topic: if you run a Claude Code build newer than v2.1.88, treat the telemetry and remote control reports as historical until you check them against your build.

Editorial conclusion

Adopt this repository if you are studying how a large CLI coding agent is put together and you want the material in English, Japanese, Korean or Chinese; the README states the content is compiled from public references and community discussion, so treat every report as a secondary source and check the claims you intend to rely on. Do not adopt it if you need a library, a template or an agent you can run today, because the repository contains reports and a directory reference, not a released artifact, and the README states commercial use is strictly prohibited. Before you spend time on it, open docs/en/ and read the report whose topic you actually care about, then check the Language line in the README for the translation you need.

Frequently asked questions

Official sources

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