corecoder 0.2.0__tar.gz → 0.3.0__tar.gz

{corecoder-0.2.0 → corecoder-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: corecoder
-Version: 0.2.0
-Summary: Minimal AI coding agent (~1300 LoC) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)
+Version: 0.3.0
+Summary: Minimal AI coding agent (~1400 LoC) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)
 Project-URL: Homepage, https://github.com/he-yufeng/CoreCoder
 Project-URL: Repository, https://github.com/he-yufeng/CoreCoder
 Project-URL: Issues, https://github.com/he-yufeng/CoreCoder/issues
@@ -13,8 +13,15 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Terminals
 Requires-Python: >=3.10
 Requires-Dist: openai>=1.0
 Requires-Dist: prompt-toolkit>=3.0
@@ -22,6 +29,8 @@ Requires-Dist: python-dotenv>=1.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm<2.0.0,>=1.60.0; extra == 'litellm'
 Description-Content-Type: text/markdown
 
 # CoreCoder
@@ -36,7 +45,7 @@ Description-Content-Type: text/markdown
 
 [中文](README_CN.md) | [English](README.md) | [Claude Code Architecture Deep Dive (7 articles)](article/)
 
-**512,000 lines of TypeScript → 950 lines of Python.**
+**512,000 lines of TypeScript → ~1,400 lines of Python.**
 
 I spent two days reverse-engineering the leaked Claude Code source — all half a million lines. Then I stripped it down to the load-bearing walls and rebuilt them in Python. The result: **every key architectural pattern from Claude Code, in a codebase you can read in one sitting.**
 
@@ -63,7 +72,7 @@ Fixed: halper → helper.
 
 ## What You Get
 
-Claude Code's 512K lines distilled to 7 patterns that actually matter:
+Claude Code's 512K lines distilled into ~1,400 lines across 7 patterns that actually matter:
 
 | Pattern | Claude Code | CoreCoder |
 |---|---|---|
@@ -114,27 +123,42 @@ corecoder -m qwen3:32b
 corecoder -p "add error handling to parse_config()"
 ```
 
+### Non-OpenAI providers (Bedrock, Vertex, Cohere, …)
+
+For providers without an OpenAI-compatible endpoint, install the optional LiteLLM extra:
+
+```bash
+pip install 'corecoder[litellm]'
+
+export CORECODER_PROVIDER=litellm
+export CORECODER_MODEL=anthropic/claude-3-haiku   # any LiteLLM model string
+export ANTHROPIC_API_KEY=sk-ant-...
+corecoder
+```
+
+LiteLLM routes through to 100+ providers (Bedrock, Vertex AI, Cohere, Groq, Replicate, Anyscale, etc.) using one model-string convention. The default `openai` backend is unchanged.
+
 ## Architecture
 
 The whole thing fits in your head:
 
 ```
 corecoder/
-├── cli.py            REPL + commands               160 lines
-├── agent.py          Agent loop + parallel tools    120 lines
-├── llm.py            Streaming client + retry       150 lines
-├── context.py        3-layer compression            145 lines
-├── session.py        Save/resume                     65 lines
-├── prompt.py         System prompt                   35 lines
-├── config.py         Env config                      30 lines
+├── cli.py            REPL + commands               218 lines
+├── agent.py          Agent loop + parallel tools    122 lines
+├── llm.py            Streaming client + retry       156 lines
+├── context.py        3-layer compression            196 lines
+├── session.py        Save/resume                     68 lines
+├── prompt.py         System prompt                   33 lines
+├── config.py         Env config                      55 lines
 └── tools/
-    ├── bash.py       Shell + safety + cd tracking    95 lines
-    ├── edit.py       Search-replace + diff            70 lines
-    ├── read.py       File reading                     40 lines
-    ├── write.py      File writing                     30 lines
-    ├── glob_tool.py  File search                      35 lines
-    ├── grep.py       Content search                   65 lines
-    └── agent.py      Sub-agent spawning               50 lines
+    ├── bash.py       Shell + safety + cd tracking   115 lines
+    ├── edit.py       Search-replace + diff            85 lines
+    ├── read.py       File reading                     53 lines
+    ├── write.py      File writing                     36 lines
+    ├── glob_tool.py  File search                      47 lines
+    ├── grep.py       Content search                   78 lines
+    └── agent.py      Sub-agent spawning               58 lines
 ```
 
 ## Use as a Library
@@ -165,9 +189,11 @@ class HttpTool(Tool):
 ## Commands
 
 ```
+/model           Show current model
 /model <name>    Switch model mid-conversation
 /compact         Compress context (like Claude Code's /compact)
-/tokens          Token usage
+/tokens          Token usage + cost estimate
+/diff            Show files modified this session
 /save            Save session to disk
 /sessions        List saved sessions
 /reset           Clear history
@@ -178,7 +204,7 @@ quit             Exit
 
 |  | Claude Code | Claw-Code | Aider | CoreCoder |
 |---|---|---|---|---|
-| Code | 512K lines (closed) | 100K+ lines | 50K+ lines | **1,300 lines** |
+| Code | 512K lines (closed) | 100K+ lines | 50K+ lines | **~1,400 lines** |
 | Models | Anthropic only | Multi | Multi | **Any OpenAI-compatible** |
 | Readable? | No | Hard | Medium | **One afternoon** |
 | Purpose | Use it | Use it | Use it | **Understand it, build yours** |
@@ -187,6 +213,21 @@ quit             Exit
 
 I wrote [7 articles](article/) breaking down Claude Code's architecture — the agent loop, tool system, context compression, streaming executor, multi-agent, and 44 hidden feature flags. If you want to understand *why* CoreCoder is designed this way, start there.
 
+## FAQ
+
+**Does CoreCoder support Skills / Subagents / MCP?**
+
+No, and that's intentional. CoreCoder is the minimal runnable core — agent loop, tools, streaming, compaction. Skills, Subagents, MCP, hooks, and plugins are upper-layer features that Claude Code layers on top; if CoreCoder had them too it would stop being a teaching artifact. The architecture articles above cover how those systems work in Claude Code, so you can add them yourself if you need to.
+
+If you want Skills specifically, the recipe is small: scan `~/.claude/skills/*.md` at startup, list their titles in the system prompt, and let the agent ask for a skill by name before you inline that file's body into the conversation.
+
+## Related Projects
+
+- **[CodeJoust](https://github.com/he-yufeng/CodeJoust)** — a CLI arena that races Claude Code, aider, Codex, and Gemini (Cursor + OpenHands next) on the same bug in isolated git worktrees, scores by tests+cost+diff+time, hands you the winning patch. If you ever wondered *which* AI coding CLI is actually better for your task, CodeJoust answers it empirically.
+- **[AnyCoder](https://github.com/he-yufeng/AnyCoder)** — a practical terminal AI coding agent built on the same architecture as CoreCoder but with litellm, session persistence, and 100+ model support. Use this one if you want a tool; use CoreCoder if you want to read source.
+- **[LiteBench](https://github.com/he-yufeng/LiteBench)** — one-command LLM / agent benchmark. Ships 7 built-in tasks (HumanEval/GSM8K/MMLU/...) and YAML-defined custom tasks, with a single-file HTML dashboard.
+- **[RepoWiki](https://github.com/he-yufeng/RepoWiki)** — open-source DeepWiki alternative. `pip install repowiki`, one command to turn any local or GitHub repo into a wiki with dependency graph, architecture diagram, and LLM-generated module pages.
+
 ## License
 
 MIT. Fork it, learn from it, ship something better. A mention of this project is appreciated.

{corecoder-0.2.0 → corecoder-0.3.0}/README.md

@@ -10,7 +10,7 @@
 
 [中文](README_CN.md) | [English](README.md) | [Claude Code Architecture Deep Dive (7 articles)](article/)
 
-**512,000 lines of TypeScript → 950 lines of Python.**
+**512,000 lines of TypeScript → ~1,400 lines of Python.**
 
 I spent two days reverse-engineering the leaked Claude Code source — all half a million lines. Then I stripped it down to the load-bearing walls and rebuilt them in Python. The result: **every key architectural pattern from Claude Code, in a codebase you can read in one sitting.**
 
@@ -37,7 +37,7 @@ Fixed: halper → helper.
 
 ## What You Get
 
-Claude Code's 512K lines distilled to 7 patterns that actually matter:
+Claude Code's 512K lines distilled into ~1,400 lines across 7 patterns that actually matter:
 
 | Pattern | Claude Code | CoreCoder |
 |---|---|---|
@@ -88,27 +88,42 @@ corecoder -m qwen3:32b
 corecoder -p "add error handling to parse_config()"
 ```
 
+### Non-OpenAI providers (Bedrock, Vertex, Cohere, …)
+
+For providers without an OpenAI-compatible endpoint, install the optional LiteLLM extra:
+
+```bash
+pip install 'corecoder[litellm]'
+
+export CORECODER_PROVIDER=litellm
+export CORECODER_MODEL=anthropic/claude-3-haiku   # any LiteLLM model string
+export ANTHROPIC_API_KEY=sk-ant-...
+corecoder
+```
+
+LiteLLM routes through to 100+ providers (Bedrock, Vertex AI, Cohere, Groq, Replicate, Anyscale, etc.) using one model-string convention. The default `openai` backend is unchanged.
+
 ## Architecture
 
 The whole thing fits in your head:
 
 ```
 corecoder/
-├── cli.py            REPL + commands               160 lines
-├── agent.py          Agent loop + parallel tools    120 lines
-├── llm.py            Streaming client + retry       150 lines
-├── context.py        3-layer compression            145 lines
-├── session.py        Save/resume                     65 lines
-├── prompt.py         System prompt                   35 lines
-├── config.py         Env config                      30 lines
+├── cli.py            REPL + commands               218 lines
+├── agent.py          Agent loop + parallel tools    122 lines
+├── llm.py            Streaming client + retry       156 lines
+├── context.py        3-layer compression            196 lines
+├── session.py        Save/resume                     68 lines
+├── prompt.py         System prompt                   33 lines
+├── config.py         Env config                      55 lines
 └── tools/
-    ├── bash.py       Shell + safety + cd tracking    95 lines
-    ├── edit.py       Search-replace + diff            70 lines
-    ├── read.py       File reading                     40 lines
-    ├── write.py      File writing                     30 lines
-    ├── glob_tool.py  File search                      35 lines
-    ├── grep.py       Content search                   65 lines
-    └── agent.py      Sub-agent spawning               50 lines
+    ├── bash.py       Shell + safety + cd tracking   115 lines
+    ├── edit.py       Search-replace + diff            85 lines
+    ├── read.py       File reading                     53 lines
+    ├── write.py      File writing                     36 lines
+    ├── glob_tool.py  File search                      47 lines
+    ├── grep.py       Content search                   78 lines
+    └── agent.py      Sub-agent spawning               58 lines
 ```
 
 ## Use as a Library
@@ -139,9 +154,11 @@ class HttpTool(Tool):
 ## Commands
 
 ```
+/model           Show current model
 /model <name>    Switch model mid-conversation
 /compact         Compress context (like Claude Code's /compact)
-/tokens          Token usage
+/tokens          Token usage + cost estimate
+/diff            Show files modified this session
 /save            Save session to disk
 /sessions        List saved sessions
 /reset           Clear history
@@ -152,7 +169,7 @@ quit             Exit
 
 |  | Claude Code | Claw-Code | Aider | CoreCoder |
 |---|---|---|---|---|
-| Code | 512K lines (closed) | 100K+ lines | 50K+ lines | **1,300 lines** |
+| Code | 512K lines (closed) | 100K+ lines | 50K+ lines | **~1,400 lines** |
 | Models | Anthropic only | Multi | Multi | **Any OpenAI-compatible** |
 | Readable? | No | Hard | Medium | **One afternoon** |
 | Purpose | Use it | Use it | Use it | **Understand it, build yours** |
@@ -161,6 +178,21 @@ quit             Exit
 
 I wrote [7 articles](article/) breaking down Claude Code's architecture — the agent loop, tool system, context compression, streaming executor, multi-agent, and 44 hidden feature flags. If you want to understand *why* CoreCoder is designed this way, start there.
 
+## FAQ
+
+**Does CoreCoder support Skills / Subagents / MCP?**
+
+No, and that's intentional. CoreCoder is the minimal runnable core — agent loop, tools, streaming, compaction. Skills, Subagents, MCP, hooks, and plugins are upper-layer features that Claude Code layers on top; if CoreCoder had them too it would stop being a teaching artifact. The architecture articles above cover how those systems work in Claude Code, so you can add them yourself if you need to.
+
+If you want Skills specifically, the recipe is small: scan `~/.claude/skills/*.md` at startup, list their titles in the system prompt, and let the agent ask for a skill by name before you inline that file's body into the conversation.
+
+## Related Projects
+
+- **[CodeJoust](https://github.com/he-yufeng/CodeJoust)** — a CLI arena that races Claude Code, aider, Codex, and Gemini (Cursor + OpenHands next) on the same bug in isolated git worktrees, scores by tests+cost+diff+time, hands you the winning patch. If you ever wondered *which* AI coding CLI is actually better for your task, CodeJoust answers it empirically.
+- **[AnyCoder](https://github.com/he-yufeng/AnyCoder)** — a practical terminal AI coding agent built on the same architecture as CoreCoder but with litellm, session persistence, and 100+ model support. Use this one if you want a tool; use CoreCoder if you want to read source.
+- **[LiteBench](https://github.com/he-yufeng/LiteBench)** — one-command LLM / agent benchmark. Ships 7 built-in tasks (HumanEval/GSM8K/MMLU/...) and YAML-defined custom tasks, with a single-file HTML dashboard.
+- **[RepoWiki](https://github.com/he-yufeng/RepoWiki)** — open-source DeepWiki alternative. `pip install repowiki`, one command to turn any local or GitHub repo into a wiki with dependency graph, architecture diagram, and LLM-generated module pages.
+
 ## License
 
 MIT. Fork it, learn from it, ship something better. A mention of this project is appreciated.

{corecoder-0.2.0 → corecoder-0.3.0}/README_CN.md

@@ -10,7 +10,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Tests](https://github.com/he-yufeng/CoreCoder/actions/workflows/ci.yml/badge.svg)](https://github.com/he-yufeng/CoreCoder/actions)
 
-**51万行 TypeScript → 950 行 Python。**
+**51万行 TypeScript → ~1,400 行 Python。**
 
 我逆向了 Claude Code 泄露的全部源码，然后把不承重的部分全扔掉，用 Python 重建了核心。成果：**Claude Code 的每一个关键架构模式，浓缩在一个下午能读完的代码库里。**
 
@@ -94,21 +94,21 @@ corecoder -p "给 parse_config() 加上错误处理"
 
 ```
 corecoder/
-├── cli.py            REPL + 命令                   160 行
-├── agent.py          Agent 循环 + 并行执行          120 行
-├── llm.py            流式客户端 + 重试              150 行
-├── context.py        三层压缩                       145 行
-├── session.py        会话保存/恢复                   65 行
-├── prompt.py         系统提示词                      35 行
-├── config.py         环境变量配置                    30 行
+├── cli.py            REPL + 命令                   218 行
+├── agent.py          Agent 循环 + 并行执行          122 行
+├── llm.py            流式客户端 + 重试              156 行
+├── context.py        三层压缩                       196 行
+├── session.py        会话保存/恢复                   68 行
+├── prompt.py         系统提示词                      33 行
+├── config.py         环境变量配置                    55 行
 └── tools/
-    ├── bash.py       Shell + 安全 + cd 追踪          95 行
-    ├── edit.py       搜索替换 + diff                  70 行
-    ├── read.py       文件读取                         40 行
-    ├── write.py      文件写入                         30 行
-    ├── glob_tool.py  文件搜索                         35 行
-    ├── grep.py       内容搜索                         65 行
-    └── agent.py      子代理生成                       50 行
+    ├── bash.py       Shell + 安全 + cd 追踪         115 行
+    ├── edit.py       搜索替换 + diff                  85 行
+    ├── read.py       文件读取                         53 行
+    ├── write.py      文件写入                         36 行
+    ├── glob_tool.py  文件搜索                         47 行
+    ├── grep.py       内容搜索                         78 行
+    └── agent.py      子代理生成                       58 行
 ```
 
 ## 当库用
@@ -139,9 +139,11 @@ class HttpTool(Tool):
 ## 命令
 
 ```
+/model           查看当前模型
 /model <名称>    切换模型
 /compact         压缩上下文（对标 Claude Code 的 /compact）
-/tokens          查看 token 用量
+/tokens          查看 token 用量 + 费用估算
+/diff            查看本次会话修改的文件
 /save            保存会话
 /sessions        列出已保存的会话
 /reset           清空历史
@@ -152,7 +154,7 @@ quit             退出
 
 |  | Claude Code | Claw-Code | Aider | CoreCoder |
 |---|---|---|---|---|
-| 代码量 | 51万行（闭源） | 10万+行 | 5万+行 | **1300 行** |
+| 代码量 | 51万行（闭源） | 10万+行 | 5万+行 | **~1,400 行** |
 | 模型 | 仅 Anthropic | 多模型 | 多模型 | **任意 OpenAI 兼容** |
 | 能通读吗？ | 不能 | 很难 | 有点费劲 | **一个下午** |
 | 适合 | 直接用 | 直接用 | 直接用 | **先看懂，再造自己的** |
@@ -161,6 +163,14 @@ quit             退出
 
 我还写了 [7 篇 Claude Code 架构深度导读](article/)：Agent 循环、工具系统、上下文压缩、流式执行、多 Agent、隐藏功能。想知道 CoreCoder 为什么这样设计，从那里开始。
 
+## FAQ
+
+**CoreCoder 支持 Skill / Subagent / MCP 吗？**
+
+不支持，这是刻意的。CoreCoder 只保留可运行的最小核心 —— agent 循环、工具、流式、压缩。Skill、Subagent、MCP、hook、plugin 都是 Claude Code 在上层加的特性；如果 CoreCoder 也全都做了，就不再是一个可读的教学产物。上面的架构导读系列讲了 Claude Code 里这些系统是怎么工作的，你可以照着自己加。
+
+如果你只是想要 Skill，配方很简单：启动时扫 `~/.claude/skills/*.md`，把标题列进 system prompt，让 agent 按名字请求某个 skill，再把那个文件的内容 inline 进对话就行了。
+
 ## License
 
 MIT。Fork，然后拿去造更好的东西，如果能标注此出处就更好了。

corecoder-0.3.0/article/00-index_EN.md

@@ -0,0 +1,35 @@
+# Claude Code Source Code Guide
+
+On March 31, 2026, a residual `.map` file in Anthropic's npm package leaked the entire source code of Claude Code. 1903 files, 512,664 lines of TypeScript.
+
+This is a series of articles I wrote after reading the entire source code. It's not a comprehensive document (that 160,000-word complete version), but it rather focuses on what I believe are the 7 most important aspects for developers to understand. Each article revolves around a core question with accurate code references.
+
+If you're working on AI Agent-related projects, you'll inevitably use these design patterns sooner or later.
+
+## Table of Contents
+
+1. **[The 510,000 Lines Codebase](01-architecture-overview_EN.md)** — Claude Code's technology stack, directory structure, and ten design philosophies. Building a global mental model.
+
+2. **[The while(true) on line 1729](02-agent-loop_EN.md)** — The core loop of the AI Agent: how query.ts drives tool calls, message orchestration, and interrupt recovery.
+
+3. **[Let AI Safely Modify Your Code](03-tool-system_EN.md)** — The ingenuity of the tool system's interface design, two-phase gating, and search-replace-edit.
+
+4. **[Finite Window, Infinite Tasks](04-context-compression_EN.md)** — Engineering details of the four-layer context compression strategy, and why it's not simply "truncating old messages".
+
+5. **[Think and Do](05-streaming-executor_EN.md)** — How StreamingToolExecutor starts executing the tool before the model has finished speaking.
+
+6. **[When One Claude Isn't Enough](06-multi-agent_EN.md)** — Multi-Agent Collaboration System: Sub-Agent Generation, Worktree Isolation, Team Orchestration.
+
+7. **[The Secret Behind Feature Flags](07-hidden-features_EN.md)** — Technical Details of 44 Unreleased Features: KAIROS Persistent Mode, Buddy Pet System, Voice Mode, Bridge Mode.
+
+## Supporting Project
+
+I've created a working reference implementation of the core architectural patterns discussed in these articles in 1300 lines of Python: [CoreCoder](https://github.com/he-yufeng/CoreCoder). You can compare the code and the articles.
+
+## Full Version
+
+You can find a comprehensive guide (16 articles, 160,000 words, covering the build system to every subsystem of the MCP protocol) [here](https://github.com/he-yufeng/CoreCoder/tree/main/docs).
+
+---
+
+Author: [He Yufeng](https://github.com/he-yufeng) · [Zhihu: Claude Code Source Code Analysis (170,000+ views)](https://zhuanlan.zhihu.com/p/1898797658343862272)

corecoder-0.3.0/article/01-architecture-overview_EN.md

@@ -0,0 +1,144 @@
+# Part 1: The 510,000 Lines Codebase
+
+`find . -name '*.ts' | wc -l` returns 1903 files. `cloc --include-lang=TypeScript .` returns 512,664 lines.
+
+To be honest, my first reaction was to close the terminal—this thing even lags for a few seconds when opened with VS Code. But I work on AI Agents (Moonshot AI / Kimi) and use Claude Code heavily every day, so I really wanted to know what was inside. So I gritted my teeth and started reading it.
+
+This is the first part of a series, and it won't delve into any specific modules. The goal is to build a mental map for you: what is Claude Code, why was its technology stack chosen this way, where are the 510,000 lines of code distributed, and the ten recurring design patterns I summarized after reading the entire code.
+
+---
+
+## Technology Stack: Bun + TypeScript + React
+
+Yes, you read that right. A terminal CLI tool uses React. 
+
+Using React for the TUI layer isn't new; Ink has been around since 2017, and it's used in Gatsby CLI and Prisma CLI.
+
+However, Claude Code's scenario is significantly more complex than a typical CLI: multiple agents running in parallel, streaming output, user interruptions during tool execution, and permission pop-ups. At this level of complexity in state management, using React is indeed more reasonable than manual development.
+
+```
+Technology Choices:
+
+  Bun          → Fast startup (4x faster than Node.js), native TypeScript support
+  TypeScript   → 510,000 lines without a type system is practically suicide
+  React + Ink  → Declarative terminal UI, complex state management
+  Commander.js → CLI parameter parsing (most mature in the Node ecosystem)
+  Zod          → Runtime data validation + automatic JSON schema generation
+  ripgrep      → Search engine written in Rust (GrepTool directly calls binary code)
+  GrowthBook   → Remote feature flags and A/B testing
+
+```
+
+TypeScript is a self-explanatory choice. Without a type system, changing a single function signature in 510,000 lines of code would cause countless system crashes. Zod is a clever choice too — it performs both runtime data validation and type inference, essentially using one schema to do two things: tell the TypeScript compiler "what the input looks like," and intercept invalid input at runtime.
+
+---
+
+## Directory Structure: Four Layers
+
+After two days of painstakingly studying Claude Code, I think it can be understood by dividing it into four layers. This isn't an official division, but rather my own mental model after reading it.
+
+### First Layer: Entry Point and UI
+
+This is the layer with things users can directly see and touch. Everything is distributed across:
+
+``` 
+  src/screens/     → React pages (REPL main interface, Onboarding, Doctor diagnostics)
+  src/components/  → UI components (permission pop-ups, tool execution progress, diff preview)
+  src/commands/    → Forward-slash commands (/commit, /compact, /model, /review)
+```
+
+`src/screens/REPL.tsx` is the main interface, over 3000 lines long, essentially the "shell" of the entire application. It handles input capture, message rendering, and command dispatch. Everything you see in the terminal originates from here.
+
+### Second Layer: The Engine
+
+The engine layer contains two files that can be thought of as Claude Code's brain. 
+
+``` 
+src/query.ts          → Core agentic loop (line 1729), while(true) loop
+src/QueryEngine.ts → Session state manager (line 1295), one instance per conversation
+```
+`QueryEngine` is the outer "container", managing state across rounds (message history, token usage, file cache). `query.ts` is the inner "engine," triggering `queryLoop()` once per user input. The latter contains  the `while(true)` loop that calls the LLM, executes tools, handles errors, and continues until the LLM provides a plain text response.
+
+[Part two of this series](02-agent-loop_EN.md) will delve deeper into `query.ts`.
+
+### Third Layer: Tools
+
+Claude Code has 30+ tools that can be seen as all capabilities that the LLM can call. A non-exhaustive list is:
+
+```
+src/tools/BashTool/         → Line 1143, the most complex single tool
+src/tools/AgentTool/        → Line 1397 (total 6700 lines in the directory), sub-agent generation
+src/tools/FileEditTool/     → Search, replace, and edit
+src/tools/FileReadTool/     → File reading
+src/tools/GrepTool/         → Ripgrep wrapper
+src/tools/GlobTool/         → File pattern matching
+src/tools/WebFetchTool/     → Web page content fetching
+src/tools/WebSearchTool/    → Web page search
+src/tools/NotebookEditTool/ → Jupyter Notebook editing
+src/tools/LSPTool/          → Language server protocol interaction
+
+...and a dozen more
+```
+Each tool is completely self-contained: schema definition, permission checks, execution logic, UI rendering, and context compression summarization are all in one directory. There's no global registry, no base class inheritance; everything is a pure object generated by the `buildTool()` factory function. This will be discussed in detail in Part 3.
+
+### Fourth Layer: Infrastructure
+
+Infrastructure is the underlying system supporting the operation of the above three layers. 
+
+``` 
+src/services/    → API client, MCP protocol, OAuth, caching
+src/utils/       → Permission system, Feature Flag, model configuration, event tracking
+src/memdir/      → Memory system (cross-session persistence)
+src/skills/      → Skill system (reusable task templates)
+src/buddy/       → Pet system (unreleased, but the code is all there)
+src/voice/       → Voice mode (codename Amber Quartz)
+src/bridge/      → Remote control mode (31 files)
+src/coordinator/ → Multi-Agent orchestration
+```
+
+The permission system deserves a separate mention: Claude Code has five permission levels, from "fully automatic" to "always ask". Tools calls go through two stages: first, `validateInput()` checks the input's validity (if invalid, it comes back to the LLM querying for a new input without a pop-up); then, `checkPermissions()` checks permissions (possibly prompting the user for confirmation). This two-phase design is clever — most rejected operations are due to invalid input, not insufficient permissions, and the two-phase design greatly reduces pop-up interruptions.
+
+---
+
+## Ten Design Philosophies
+
+After reading 500,000 lines of code, some patterns recurred. I've tried to summarize them into ten, which will be cited in each subsequent article.
+
+**1. Externalize State.** All external dependencies of `QueryEngine` are injected through `QueryEngineConfig` (20+ fields), not imported internally. This means you can pass a mock list of tools and API clients into unit tests without starting the entire application.
+
+**2. Incremental Complexity.** Keep simple things simple. `FileReadTool` has only a few dozen lines; `BashTool` has 1143 lines. Not every tool needs the same complexity; complexity should be concentrated where it's needed.
+
+**3. Feature Flag Gating.** 44 compile-time/runtime flags. A feature failed internal validation? It's deleted at compile time, leaving no string. This isn't a "if (false)" style fake deletion; it's a physical deletion via DCE (Dead Code Elimination) in Bundle.
+
+**4. Type as Documentation.** The Zod schema performs both validation and type inference. The field names in the `ToolDef` type are the most accurate interface documentation. Newcomers can understand which methods a tool needs to implement just by looking at the type definition.
+
+**5. Context Economics.** Tokens are like money. Tool output exceeding a threshold is written to disk, but only a digest is left in the context. The context has four layers of compression. The `getToolUseSummary()` method defines the digest strategy for each tool during compression.
+
+**6. Security Layering.** Two-phase gating (authentication + permissions), five-level permission mode, BashTool's command classifier (parses commands into search/read/write categories to match permission rules), macOS sandbox-exec / Linux seccomp sandbox. Security isn't a single wall, it's multiple walls.
+
+**7. Graceful Degradation.** API timeout retries (exponential backoff, maximum 5 times). If the model doesn't support `stream_options`, remove that parameter and retry. Sub-Agent crashes don't affect the main loop. Output hitting `max_output_tokens` limits automatic retries to a maximum of 3 times.
+
+**8. Declarative Configuration.** Tools, commands, Skills, and Agent types are all declarative. A Skill is simply a `.md` file with a YAML frontmatter. An Agent type is a configuration object. Assembled on demand at runtime, no registration required in the code.
+
+**9. Streaming Everything.** **API response streaming:** StreamingToolExecutor begins executing the tool while the model is still outputting, pushing progress information to the terminal in real time. Users always see progress, instead of waiting for a long task to complete.
+
+**10. Experimental Progress:** Ablative testing infrastructure (`ABLATION_BASELINE` allows for one-click shutdown of thinking/compact/memory/background), A/B testing flags, and the ability to run controlled experiments to quantify the value of each feature before launch. It's not about "launching because it feels useful," but about "launching only when the data says it's useful."
+
+---
+
+## About this series
+
+The following six articles will delve deeper into each of these:
+
+- Article 2: The while(true) loop on line 1729 of `query.ts`
+- Article 3: The design of the tool system and search, replace, and edit
+- Article 4: Four-layer context compression
+- Article 5: Parallelism of streaming tools in StreamingToolExecutor
+- Article 6: Multi-Agent Collaboration System
+- Article 7: Unreleased features behind Feature Flag
+
+I also replicated these core design patterns in 1300 lines of Python: [CoreCoder](https://github.com/he-yufeng/CoreCoder). Each article will explain the source code and the CoreCoder implementation.
+
+---
+
+> This article is the first in the [Claude Code Source Code Guide](00-index.md) series.