corecoder 0.4.0__tar.gz → 0.4.1__tar.gz

{corecoder-0.4.0 → corecoder-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: corecoder
-Version: 0.4.0
+Version: 0.4.1
 Summary: Minimal AI coding agent (~1,000 lines of Python) 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
@@ -52,17 +52,28 @@ Description-Content-Type: text/markdown
 
 </div>
 
-- **Readable end to end.** Read the whole engine in an afternoon: 1,081 lines of pure Python, with no magic hidden anywhere you can't follow it.
-- **Hackable.** Set a breakpoint on any line, change it, rerun, all on your own machine. It genuinely works, which makes this a living reference rather than a diagram. It just isn't meant to be your daily driver.
+- **Readable end to end.** Read the whole engine in an afternoon, with no magic hidden anywhere you can't follow it.
+- **Hackable.** Set a breakpoint on any line, change it, rerun, all on your own machine. It genuinely works, which makes this a living reference rather than a diagram.
 - **The gaps are the point.** It deliberately keeps only the minimal core; what's missing isn't half-finished, it's where you branch off and make it your own.
 
+## How it compares
+
+| | CoreCoder | Claude Code | aider | nanoGPT |
+|---|---|---|---|---|
+| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
+| Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
+| What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
+
+The nanoGPT column is there as a reference point: minimal, readable, but it teaches you to train a GPT. CoreCoder is after the same thing, only the subject is an agent that actually edits code. Sitting it next to Claude Code and aider isn't about competing for their users. CoreCoder is the foundation you stand on while you learn from them and get going; it isn't in the same race.
+
 ## What this is
 
 I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly.
 
 The engine (loop, model interface, context, tools, sessions) is 1,081 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 18 files: 1,714 physical lines, 1,385 net, every one short enough to read in a single sitting.
 
-And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 86 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
+And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 103 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
 
 The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change.
 
@@ -93,6 +104,7 @@ Give it a model and a key and it goes. It speaks the OpenAI-compatible API by de
 |---|---|
 | OpenAI (default `gpt-5.5`) | `OPENAI_API_KEY=sk-...` |
 | DeepSeek | `OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com CORECODER_MODEL=deepseek-chat` |
+| OmniRoute | `OPENAI_API_KEY=your-key OPENAI_BASE_URL=http://localhost:20128/v1 CORECODER_MODEL=auto` |
 | Local Ollama | `OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder` |
 
 Kimi, Qwen and the like are the same two variables; for providers that don't even offer an OpenAI-compatible endpoint, the optional LiteLLM backend (`pip install "corecoder[litellm]"`) routes to a hundred-plus of them. The third essay goes into this in detail. The key can be `export`ed directly or dropped into a `.env` at the project root, which is loaded on startup. Then:
@@ -108,7 +120,7 @@ Laid out flat, the whole project is this big. Skim it before you clone and you'l
 
 ```
 corecoder/
-├── agent.py        agent loop + parallel tool exec       150 lines   ← start here
+├── agent.py        agent loop + parallel tool exec       162 lines   ← start here
 ├── llm.py          streaming client + retry + cost        336 lines
 ├── context.py      three-tier context compaction          210 lines
 ├── session.py      save / resume + path-traversal guard    97 lines
@@ -122,11 +134,12 @@ corecoder/
     ├── glob_tool.py  filename matching                     47 lines
     ├── read.py       file read                             53 lines
     ├── write.py      file write                            38 lines
+    ├── todo.py       agent-maintained task checklist       79 lines
     ├── agent.py      sub-agent spawning                    58 lines
     └── base.py       tool base class                       27 lines
 ```
 
-Seven tools: `bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, and `agent` (which spawns a sub-agent). Add the packaging files like `__init__` and `__main__` and the package is 18 files; strip the CLI shell and config and the engine itself is about 1,081 lines.
+Eight tools: `bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `todo_write` (a task checklist the agent maintains for itself), and `agent` (which spawns a sub-agent). Everything else is the CLI shell, config, and packaging wrapped around that engine core.
 
 ## A `while` loop is the whole agent
 
@@ -147,7 +160,7 @@ def chat(self, user_input):
     return "(hit the round limit)"
 ```
 
-That's the whole thing. The core skeleton is about twenty lines; counting parallel execution and the bookkeeping after a Ctrl+C interrupt, maybe forty. Almost everything else in CoreCoder's thousand-odd lines is there to clean up the mess that shows up once the loop runs against the real world. `llm.py` is the biggest file in the project, not because calling a model is hard, but because in a streamed response a single tool call's arguments arrive in several fragments, one after another, and you have to stitch them back together in order. A provider will occasionally hand you half a JSON object, or fill the `usage` field with null; rate limits (429), timeouts, dropped connections and 5xx all need backoff-and-retry, while the other 4xx should just raise instead of being retried into the ground. Even an OpenAI extension like `stream_options` gets handled: some providers reject it outright with a 400, so the code strips it and resends exactly once, only on a 400, and never stacks that on top of the retry backoff. Lay all this grunt work out and it's the genuinely hard engineering part of taking an agent from demo to delivery. The unglamorous part turns out to be the loop itself; the thousand lines of fallback around it are where the real work lives.
+That's the whole thing. The core skeleton is about twenty lines; counting parallel execution and the bookkeeping after a Ctrl+C interrupt, maybe forty. Almost everything else in CoreCoder's thousand-odd lines is there to clean up the mess the loop runs into once it meets the real world. `llm.py` ends up the biggest file in the project, not because calling a model is hard, but because a streamed response splinters each tool call's arguments into fragments you have to restitch in order, a provider will hand you half a JSON object or a null `usage` field, and 429s, timeouts, dropped connections and 5xx all need backoff-and-retry while the other 4xx should just raise. That unglamorous grunt work, not the loop, is where the real engineering of taking an agent from demo to delivery actually lives; the third essay follows it down to the line.
 
 Three decisions are worth a closer look, because they're the kind of call you can only make after you've understood how others did it, and they're judgments you can lift straight into your own fork.
 
@@ -197,17 +210,6 @@ Going deeper, the directions are out in the open too. None of the following is i
 
 The README only points; the seventh essay picks up the code details for each. Pick one and start; that's the whole reason the core is kept this small.
 
-## How it compares
-
-| | CoreCoder | Claude Code | aider | nanoGPT |
-|---|---|---|---|---|
-| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
-| Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
-| Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
-| What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
-
-The nanoGPT column is there as a reference point: minimal, readable, but it teaches you to train a GPT. CoreCoder is after the same thing, only the subject is an agent that actually edits code. Sitting it next to Claude Code and aider isn't about competing for their users. CoreCoder is the foundation you stand on while you learn from them and get going; it isn't in the same race.
-
 ## Commands
 
 Inside the REPL, `/help` lists everything; these are the ones you'll reach for:
@@ -223,9 +225,19 @@ quit / exit      exit (Ctrl+C cancels the current round)
 
 Session IDs are sanitized to safe characters before they become filenames, every archive lands under `~/.corecoder/sessions`, and a malicious session name can't traverse out.
 
+## Related Projects
+
+If working through CoreCoder was useful, here are a few other tools I've built around agents and LLM systems:
+
+- **[RepoWiki](https://github.com/he-yufeng/RepoWiki)** — dropped into an unfamiliar codebase? It gives you a guided wiki and a where-to-start reading path, a self-hostable DeepWiki alternative.
+- **[FindJobs-Agent](https://github.com/he-yufeng/FindJobs-Agent)** — stop sifting job boards by hand: it ranks postings against your resume and runs mock interviews.
+- **[ContractGuard](https://github.com/he-yufeng/ContractGuard)** — catch the risky clauses before you sign: it reads contracts and flags the dangerous bits.
+- **[GitSense](https://github.com/he-yufeng/GitSense)** — want to contribute to open source? It finds issues worth your time and gauges whether your PR will get merged.
+- **[CodeABC](https://github.com/he-yufeng/CodeABC)** — understand any codebase even if you don't code, built for non-programmers.
+
 ## Contributing / License
 
-Before you send anything, run `pytest tests/ -q` (86 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
+Before you send anything, run `pytest tests/ -q` (103 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
 
 ---
 

{corecoder-0.4.0 → corecoder-0.4.1}/README.md

@@ -17,17 +17,28 @@
 
 </div>
 
-- **Readable end to end.** Read the whole engine in an afternoon: 1,081 lines of pure Python, with no magic hidden anywhere you can't follow it.
-- **Hackable.** Set a breakpoint on any line, change it, rerun, all on your own machine. It genuinely works, which makes this a living reference rather than a diagram. It just isn't meant to be your daily driver.
+- **Readable end to end.** Read the whole engine in an afternoon, with no magic hidden anywhere you can't follow it.
+- **Hackable.** Set a breakpoint on any line, change it, rerun, all on your own machine. It genuinely works, which makes this a living reference rather than a diagram.
 - **The gaps are the point.** It deliberately keeps only the minimal core; what's missing isn't half-finished, it's where you branch off and make it your own.
 
+## How it compares
+
+| | CoreCoder | Claude Code | aider | nanoGPT |
+|---|---|---|---|---|
+| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
+| Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
+| Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
+| What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
+
+The nanoGPT column is there as a reference point: minimal, readable, but it teaches you to train a GPT. CoreCoder is after the same thing, only the subject is an agent that actually edits code. Sitting it next to Claude Code and aider isn't about competing for their users. CoreCoder is the foundation you stand on while you learn from them and get going; it isn't in the same race.
+
 ## What this is
 
 I've always felt coding agents get talked about as if they were arcane. Strip a tool like Claude Code or Cursor all the way down and the core is a `while` loop wrapped around a large model, plus seven or eight tools that let it actually do things. The hard part was never the loop; it's everything the loop has to cope with once it meets the real world. CoreCoder is the minimal version that writes that core out honestly.
 
 The engine (loop, model interface, context, tools, sessions) is 1,081 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 18 files: 1,714 physical lines, 1,385 net, every one short enough to read in a single sitting.
 
-And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 86 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
+And it really runs: reads and writes files, executes shell, spawns sub-agents, compacts context in three tiers, and tells you the tokens and dollars a run burned whenever you ask. 103 tests, all green. But the point of it running isn't to become your daily driver. It runs so the walkthrough can't lie: a reference that shows how an agent works has to actually work.
 
 The code came out of a public teardown: open analyses have already exposed a lot of the load-bearing architecture inside production agents like Claude Code. I took the most essential layer and rewrote it honestly, in as little code as I could. So reading CoreCoder is roughly like reading a runnable, annotated take on how that kind of agent works, except it's only a minimal reimplementation, sitting right there on your machine for you to take apart and change.
 
@@ -58,6 +69,7 @@ Give it a model and a key and it goes. It speaks the OpenAI-compatible API by de
 |---|---|
 | OpenAI (default `gpt-5.5`) | `OPENAI_API_KEY=sk-...` |
 | DeepSeek | `OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com CORECODER_MODEL=deepseek-chat` |
+| OmniRoute | `OPENAI_API_KEY=your-key OPENAI_BASE_URL=http://localhost:20128/v1 CORECODER_MODEL=auto` |
 | Local Ollama | `OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder` |
 
 Kimi, Qwen and the like are the same two variables; for providers that don't even offer an OpenAI-compatible endpoint, the optional LiteLLM backend (`pip install "corecoder[litellm]"`) routes to a hundred-plus of them. The third essay goes into this in detail. The key can be `export`ed directly or dropped into a `.env` at the project root, which is loaded on startup. Then:
@@ -73,7 +85,7 @@ Laid out flat, the whole project is this big. Skim it before you clone and you'l
 
 ```
 corecoder/
-├── agent.py        agent loop + parallel tool exec       150 lines   ← start here
+├── agent.py        agent loop + parallel tool exec       162 lines   ← start here
 ├── llm.py          streaming client + retry + cost        336 lines
 ├── context.py      three-tier context compaction          210 lines
 ├── session.py      save / resume + path-traversal guard    97 lines
@@ -87,11 +99,12 @@ corecoder/
     ├── glob_tool.py  filename matching                     47 lines
     ├── read.py       file read                             53 lines
     ├── write.py      file write                            38 lines
+    ├── todo.py       agent-maintained task checklist       79 lines
     ├── agent.py      sub-agent spawning                    58 lines
     └── base.py       tool base class                       27 lines
 ```
 
-Seven tools: `bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, and `agent` (which spawns a sub-agent). Add the packaging files like `__init__` and `__main__` and the package is 18 files; strip the CLI shell and config and the engine itself is about 1,081 lines.
+Eight tools: `bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `todo_write` (a task checklist the agent maintains for itself), and `agent` (which spawns a sub-agent). Everything else is the CLI shell, config, and packaging wrapped around that engine core.
 
 ## A `while` loop is the whole agent
 
@@ -112,7 +125,7 @@ def chat(self, user_input):
     return "(hit the round limit)"
 ```
 
-That's the whole thing. The core skeleton is about twenty lines; counting parallel execution and the bookkeeping after a Ctrl+C interrupt, maybe forty. Almost everything else in CoreCoder's thousand-odd lines is there to clean up the mess that shows up once the loop runs against the real world. `llm.py` is the biggest file in the project, not because calling a model is hard, but because in a streamed response a single tool call's arguments arrive in several fragments, one after another, and you have to stitch them back together in order. A provider will occasionally hand you half a JSON object, or fill the `usage` field with null; rate limits (429), timeouts, dropped connections and 5xx all need backoff-and-retry, while the other 4xx should just raise instead of being retried into the ground. Even an OpenAI extension like `stream_options` gets handled: some providers reject it outright with a 400, so the code strips it and resends exactly once, only on a 400, and never stacks that on top of the retry backoff. Lay all this grunt work out and it's the genuinely hard engineering part of taking an agent from demo to delivery. The unglamorous part turns out to be the loop itself; the thousand lines of fallback around it are where the real work lives.
+That's the whole thing. The core skeleton is about twenty lines; counting parallel execution and the bookkeeping after a Ctrl+C interrupt, maybe forty. Almost everything else in CoreCoder's thousand-odd lines is there to clean up the mess the loop runs into once it meets the real world. `llm.py` ends up the biggest file in the project, not because calling a model is hard, but because a streamed response splinters each tool call's arguments into fragments you have to restitch in order, a provider will hand you half a JSON object or a null `usage` field, and 429s, timeouts, dropped connections and 5xx all need backoff-and-retry while the other 4xx should just raise. That unglamorous grunt work, not the loop, is where the real engineering of taking an agent from demo to delivery actually lives; the third essay follows it down to the line.
 
 Three decisions are worth a closer look, because they're the kind of call you can only make after you've understood how others did it, and they're judgments you can lift straight into your own fork.
 
@@ -162,17 +175,6 @@ Going deeper, the directions are out in the open too. None of the following is i
 
 The README only points; the seventh essay picks up the code details for each. Pick one and start; that's the whole reason the core is kept this small.
 
-## How it compares
-
-| | CoreCoder | Claude Code | aider | nanoGPT |
-|---|---|---|---|---|
-| Lines of code | ~1,081 engine / 1,714 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) |
-| Time to read it all | one afternoon | can't (closed) | a few days of slogging | one afternoon |
-| Breakpoint, change, rerun? | yes, every line | no | yes, but there's a lot | yes |
-| What it's for | understand one, then fork your own | production coding assistant | terminal pair-programming | minimal GPT for teaching |
-
-The nanoGPT column is there as a reference point: minimal, readable, but it teaches you to train a GPT. CoreCoder is after the same thing, only the subject is an agent that actually edits code. Sitting it next to Claude Code and aider isn't about competing for their users. CoreCoder is the foundation you stand on while you learn from them and get going; it isn't in the same race.
-
 ## Commands
 
 Inside the REPL, `/help` lists everything; these are the ones you'll reach for:
@@ -188,9 +190,19 @@ quit / exit      exit (Ctrl+C cancels the current round)
 
 Session IDs are sanitized to safe characters before they become filenames, every archive lands under `~/.corecoder/sessions`, and a malicious session name can't traverse out.
 
+## Related Projects
+
+If working through CoreCoder was useful, here are a few other tools I've built around agents and LLM systems:
+
+- **[RepoWiki](https://github.com/he-yufeng/RepoWiki)** — dropped into an unfamiliar codebase? It gives you a guided wiki and a where-to-start reading path, a self-hostable DeepWiki alternative.
+- **[FindJobs-Agent](https://github.com/he-yufeng/FindJobs-Agent)** — stop sifting job boards by hand: it ranks postings against your resume and runs mock interviews.
+- **[ContractGuard](https://github.com/he-yufeng/ContractGuard)** — catch the risky clauses before you sign: it reads contracts and flags the dangerous bits.
+- **[GitSense](https://github.com/he-yufeng/GitSense)** — want to contribute to open source? It finds issues worth your time and gauges whether your PR will get merged.
+- **[CodeABC](https://github.com/he-yufeng/CodeABC)** — understand any codebase even if you don't code, built for non-programmers.
+
 ## Contributing / License
 
-Before you send anything, run `pytest tests/ -q` (86 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
+Before you send anything, run `pytest tests/ -q` (103 tests), `ruff check`, and `compileall`, and make sure they're green. MIT licensed: fork it, learn from it, ship something better. A mention of this project is appreciated.
 
 ---
 

{corecoder-0.4.0 → corecoder-0.4.1}/README_CN.md

@@ -17,17 +17,28 @@
 
 </div>
 
-- **读得完。** 一个下午读完整个引擎，1081 行纯 Python，没有一处藏着你看不懂的魔法。
-- **改得动。** 每一行都能在你自己机器上下断点、改了再跑。它真能干活，所以这份参考是活的，不是示意图；但它不是拿来当日常工具的。
+- **读得完。** 一个下午读完整个引擎，没有一处藏着你看不懂的魔法。
+- **改得动。** 每一行都能在你自己机器上下断点、改了再跑。它真能干活，所以这份参考是活的，不是示意图。
 - **留白即起点。** 刻意只留最小核心，没做的那些不是半成品，是留给你 fork 出更好东西的地方。
 
+## 和谁比
+
+| | CoreCoder | Claude Code | aider | nanoGPT |
+|---|---|---|---|---|
+| 代码量 | 引擎约 1081 行 / 整包 1714 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
+| 读完要多久 | 一个下午 | 读不了（闭源） | 得啃几天 | 一个下午 |
+| 能不能下断点改了再跑 | 能，每一行 | 不能 | 能，但量大 | 能 |
+| 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT |
+
+nanoGPT 那一列是拿来对照的：它最小、可读，但教的是训一个 GPT。CoreCoder 想干的是同一件事，只是把对象换成一个能真正改代码的 agent。和 Claude Code、aider 摆在一起，不是要跟它们抢用户，CoreCoder 是借它们来学、来起步的那块地基，根本不在一个赛道。
+
 ## 这是什么
 
 我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底，核心是一个 while 循环套着一个大模型，外加七八个让它能真正动手的工具。难的从来不是这个循环，而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。
 
 引擎部分（循环、模型接口、上下文、工具、会话）去掉空行和注释是 1081 行。连最外层的 CLI、配置、打包一起算，整个包 18 个文件、物理 1714 行、净 1385 行，每个文件都短到能一口气读完。
 
-它真能跑：读写文件、执行 shell、派子 agent、分三层压上下文，还能随时把这趟烧掉的 token 和美元数报给你，86 个测试是绿的。但能跑不是为了劝你拿去日用，而是为了让这份「注释」不撒谎：一个解释 agent 怎么运作的范例，自己得真能运作。
+它真能跑：读写文件、执行 shell、派子 agent、分三层压上下文，还能随时把这趟烧掉的 token 和美元数报给你，103 个测试是绿的。但能跑不是为了劝你拿去日用，而是为了让这份「注释」不撒谎：一个解释 agent 怎么运作的范例，自己得真能运作。
 
 代码来自一次公开拆解。公开的源码分析里，Claude Code 这类生产级 agent 暴露出不少关键架构，我挑出最核心的一层，用尽量少的代码诚实地复写了一遍。所以读 CoreCoder，约等于读一份基于公开源码分析的「可运行注释版」：讲的是这类 agent 的核心思路，而它本身只是最小复写，就摆在你机器上，随你拆、随你改。
 
@@ -58,6 +69,7 @@ pip install -e .
 |---|---|
 | OpenAI（默认 `gpt-5.5`） | `OPENAI_API_KEY=sk-...` |
 | DeepSeek | `OPENAI_API_KEY=sk-... OPENAI_BASE_URL=https://api.deepseek.com CORECODER_MODEL=deepseek-chat` |
+| OmniRoute | `OPENAI_API_KEY=your-key OPENAI_BASE_URL=http://localhost:20128/v1 CORECODER_MODEL=auto` |
 | 本地 Ollama | `OPENAI_API_KEY=ollama OPENAI_BASE_URL=http://localhost:11434/v1 CORECODER_MODEL=qwen2.5-coder` |
 
 Kimi、Qwen 这些同样是改这两个变量；连 OpenAI 兼容接口都不给的 provider，装上可选的 LiteLLM 后端（`pip install "corecoder[litellm]"`）能路由一百多家。第三篇文章把这块讲得更细。key 可以直接 `export`，也可以在项目根目录扔个 `.env`，启动时自动加载。然后：
@@ -73,7 +85,7 @@ corecoder -p "给 parse_config() 加错误处理"   # 一次性模式，干完
 
 ```
 corecoder/
-├── agent.py        agent 主循环 + 并行工具执行       150 行   ← 从这里开始读
+├── agent.py        agent 主循环 + 并行工具执行       162 行   ← 从这里开始读
 ├── llm.py          流式客户端 + 重试 + 成本统计       336 行
 ├── context.py      三层上下文压缩                     210 行
 ├── session.py      会话存盘 / 续聊 + 路径穿越防护      97 行
@@ -87,11 +99,12 @@ corecoder/
     ├── glob_tool.py  文件名匹配                         47 行
     ├── read.py       文件读取                           53 行
     ├── write.py      文件写入                           38 行
+    ├── todo.py       agent 自维护的任务清单            79 行
     ├── agent.py      子 agent 派生                      58 行
     └── base.py       工具基类                           27 行
 ```
 
-七个工具：`bash`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`agent`（派子 agent）。再加上 `__init__`、`__main__` 这些打包文件，整包 18 个文件；剥掉 CLI 外壳和配置，引擎本身约 1081 行。
+八个工具：`bash`、`read_file`、`write_file`、`edit_file`、`glob`、`grep`、`todo_write`（agent 自己维护的任务清单）、`agent`（派子 agent）。其余都是包在引擎核心外面的 CLI 外壳、配置和打包。
 
 ## 一个 while 循环就是 agent 的本体
 
@@ -112,7 +125,7 @@ def chat(self, user_input):
     return "(已达轮次上限)"
 ```
 
-就这么点。这个循环的核心骨架就二十来行，把并行执行和被 Ctrl+C 打断后的回填都算上，也才四十多行。CoreCoder 一千多行里剩下的，几乎全在收拾它真跑起来之后冒出来的岔子。`llm.py` 是全项目最大的文件，不是因为调模型有多难，而是流式返回里，一个工具调用的参数会被切成好几段先后送到，你得按顺序拼回去；provider 偶尔吐半截 JSON，或者把 usage 字段填成 null；限流（429）、超时、连接中断和 5xx 都得退避重试，其余 4xx 该直接抛就别硬试。连 `stream_options` 这种 OpenAI 扩展都照顾到了：有的 provider 直接回 400 拒收，代码就只在 400 时把它摘掉重发一次，绝不和退避重试叠上去。这些脏活摊开来，恰恰是一个 agent 从能演示走到能交付，工程上最费劲的那部分。祛魅祛的是那个循环，不是这一千行兜底。
+就这么点。这个循环的核心骨架就二十来行，把并行执行和被 Ctrl+C 打断后的回填都算上，也才四十多行。CoreCoder 一千多行里剩下的，几乎全在收拾它真跑起来之后冒出来的岔子。`llm.py` 最后成了全项目最大的文件，不是因为调模型有多难，而是流式返回里一个工具调用的参数会被切成好几段先后送到、得按顺序拼回去，provider 偶尔吐半截 JSON 或把 usage 填成 null，限流（429）、超时、连接中断和 5xx 都得退避重试，其余 4xx 该直接抛就别硬试。这些不起眼的脏活，而不是那个循环，才是一个 agent 从能演示走到能交付真正吃工程功夫的地方；第三篇文章顺着它拆到每一行。
 
 有三个决定值得单独看，因为它们是「先读懂别人怎么做」之后才做得出的取舍，也是你 fork 自己 agent 时可以直接抄走的判断。
 
@@ -162,17 +175,6 @@ print(Agent(llm=llm).chat("找出项目里所有 TODO 注释并列出来"))
 
 README 只给方向，每条的代码细节第七篇接着讲。挑一个动手，就是把它做得更好的开始。
 
-## 和谁比
-
-| | CoreCoder | Claude Code | aider | nanoGPT |
-|---|---|---|---|---|
-| 代码量 | 引擎约 1081 行 / 整包 1714 行 | 几十万行（闭源） | 数万行 Python | 约 600 行（两个文件） |
-| 读完要多久 | 一个下午 | 读不了（闭源） | 得啃几天 | 一个下午 |
-| 能不能下断点改了再跑 | 能，每一行 | 不能 | 能，但量大 | 能 |
-| 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT |
-
-nanoGPT 那一列是拿来对照的：它最小、可读，但教的是训一个 GPT。CoreCoder 想干的是同一件事，只是把对象换成一个能真正改代码的 agent。和 Claude Code、aider 摆在一起，不是要跟它们抢用户，CoreCoder 是借它们来学、来起步的那块地基，根本不在一个赛道。
-
 ## 命令
 
 进了 REPL，`/help` 列全部，常用的这几个：
@@ -188,9 +190,19 @@ quit / exit      退出（Ctrl+C 取消当前回合）
 
 会话 ID 会先清洗成安全字符再拿去当文件名，存档统统落在 `~/.corecoder/sessions` 里，恶意会话名穿越不出去。
 
+## 相关项目
+
+如果你读 CoreCoder 读得还顺，下面几个我做的 agent / LLM 系统方向的工具也许用得上：
+
+- **[RepoWiki](https://github.com/he-yufeng/RepoWiki)** — 被丢进一个陌生代码库？它给你一份带「从哪读起」路径的 wiki，一个可自托管的 DeepWiki 替代。
+- **[FindJobs-Agent](https://github.com/he-yufeng/FindJobs-Agent)** — 别再手动刷招聘网站：它按你的简历给岗位排序，还能跑模拟面试。
+- **[ContractGuard](https://github.com/he-yufeng/ContractGuard)** — 签字前先把有风险的条款挑出来：它读合同、标出危险点。
+- **[GitSense](https://github.com/he-yufeng/GitSense)** — 想给开源做贡献？它帮你找到值得做的 issue，还能估你的 PR 多大概率被合。
+- **[CodeABC](https://github.com/he-yufeng/CodeABC)** — 不会写代码也能看懂一个项目，专给小白做的。
+
 ## 贡献 / License
 
-动手之前先跑一遍 `pytest tests/ -q`（86 个测试）、`ruff check` 和 `compileall`，绿了再提。MIT License，欢迎 fork 拿去造更好的东西，能在 README 里留一句出处就更好。
+动手之前先跑一遍 `pytest tests/ -q`（103 个测试）、`ruff check` 和 `compileall`，绿了再提。MIT License，欢迎 fork 拿去造更好的东西，能在 README 里留一句出处就更好。
 
 ---
 

{corecoder-0.4.0 → corecoder-0.4.1}/corecoder/__init__.py

@@ -1,10 +1,10 @@
 """CoreCoder - Minimal AI coding agent inspired by Claude Code's architecture."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 from corecoder.agent import Agent
-from corecoder.llm import LLM
 from corecoder.config import Config
+from corecoder.llm import LLM
 from corecoder.tools import ALL_TOOLS
 
-__all__ = ["Agent", "LLM", "Config", "ALL_TOOLS", "__version__"]
+__all__ = ["ALL_TOOLS", "LLM", "Agent", "Config", "__version__"]

{corecoder-0.4.0 → corecoder-0.4.1}/corecoder/agent.py

@@ -11,12 +11,14 @@ which means it's done working and ready to report back.
 
 import concurrent.futures
 import inspect
+
+from .context import ContextManager
 from .llm import LLM
+from .prompt import system_prompt
 from .tools import ALL_TOOLS
-from .tools.base import Tool
 from .tools.agent import AgentTool
-from .prompt import system_prompt
-from .context import ContextManager
+from .tools.base import Tool
+from .tools.todo import TodoWriteTool
 
 
 class Agent:
@@ -40,8 +42,17 @@ class Agent:
             if isinstance(t, AgentTool):
                 t._parent_agent = self
 
+        self._todo = next((t for t in self.tools if isinstance(t, TodoWriteTool)), None)
+
     def _full_messages(self) -> list[dict]:
-        return [{"role": "system", "content": self._system}] + self.messages
+        system = self._system
+        # the task list is re-injected every round, so the model always sees the
+        # current state rather than a stale copy buried in old tool results
+        if self._todo is not None:
+            rendered = self._todo.render()
+            if rendered:
+                system += "\n\n# Current task list\n" + rendered
+        return [{"role": "system", "content": system}] + self.messages
 
     def _tool_schemas(self) -> list[dict]:
         return [t.schema() for t in self.tools]
@@ -109,9 +120,10 @@ class Agent:
             inspect.signature(tool.execute).bind(**tc.arguments)
         except TypeError as e:
             return f"Error: bad arguments for {tc.name}: {e}"
+        # a tool that blows up gets reported back as text, never kills the loop
         try:
             return tool.execute(**tc.arguments)
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
             return f"Error executing {tc.name}: {e}"
 
     def _exec_tools_parallel(self, tool_calls, on_tool=None) -> list[str]:

{corecoder-0.4.0 → corecoder-0.4.1}/corecoder/cli.py

@@ -1,21 +1,21 @@
 """Interactive REPL - the user-facing terminal interface."""
 
-import sys
-import os
 import argparse
+import os
+import sys
 
-from rich.console import Console
-from rich.markdown import Markdown
-from rich.panel import Panel
 from prompt_toolkit import prompt as pt_prompt
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.key_binding import KeyBindings
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
 
+from . import __version__
 from .agent import Agent
-from .llm import LLM, LiteLLM
 from .config import Config
-from .session import save_session, load_session, list_sessions
-from . import __version__
+from .llm import LLM, LiteLLM
+from .session import list_sessions, load_session, save_session
 
 console = Console()
 
@@ -29,6 +29,7 @@ def _parse_args():
     p.add_argument("--base-url", help="API base URL (default: $OPENAI_BASE_URL)")
     p.add_argument("--api-key", help="API key (default: $OPENAI_API_KEY)")
     p.add_argument("-p", "--prompt", help="One-shot prompt (non-interactive mode)")
+    p.add_argument("--demo", action="store_true", help="Run the offline scripted demo (no API key needed)")
     p.add_argument("-r", "--resume", metavar="ID", help="Resume a saved session")
     p.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
     return p.parse_args()
@@ -36,6 +37,11 @@ def _parse_args():
 
 def main():
     args = _parse_args()
+
+    if args.demo:
+        from .demo import run_demo
+        raise SystemExit(run_demo())
+
     config = Config.from_env()
 
     # CLI args override env vars
@@ -108,7 +114,8 @@ def _run_once(agent: Agent, prompt: str):
     except KeyboardInterrupt:
         console.print("\n[yellow]Interrupted.[/yellow]")
         sys.exit(130)
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
+        # one-shot mode: print whatever went wrong and exit non-zero
         console.print(f"\n[red]Error: {e}[/red]")
         sys.exit(1)
     print()
@@ -223,7 +230,7 @@ def _repl(agent: Agent, config: Config):
         # call the agent
         streamed: list[str] = []
 
-        def on_token(tok):
+        def on_token(tok, streamed=streamed):
             streamed.append(tok)
             print(tok, end="", flush=True)
 
@@ -239,7 +246,8 @@ def _repl(agent: Agent, config: Config):
                 console.print(Markdown(response))
         except KeyboardInterrupt:
             console.print("\n[yellow]Interrupted.[/yellow]")
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
+            # keep the REPL alive no matter what chat() throws
             console.print(f"\n[red]Error: {e}[/red]")
 
 

{corecoder-0.4.0 → corecoder-0.4.1}/corecoder/context.py

@@ -13,6 +13,7 @@ CoreCoder implements the same idea in 3 layers:
 """
 
 from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -48,16 +49,14 @@ class ContextManager:
         compressed = False
 
         # Layer 1: snip verbose tool outputs
-        if current > self._snip_at:
-            if self._snip_tool_outputs(messages):
-                compressed = True
-                current = estimate_tokens(messages)
+        if current > self._snip_at and self._snip_tool_outputs(messages):
+            compressed = True
+            current = estimate_tokens(messages)
 
         # Layer 2: LLM-powered summarization of old turns
-        if current > self._summarize_at and len(messages) > 10:
-            if self._summarize_old(messages, llm, keep_recent=8):
-                compressed = True
-                current = estimate_tokens(messages)
+        if current > self._summarize_at and len(messages) > 10 and self._summarize_old(messages, llm, keep_recent=8):
+            compressed = True
+            current = estimate_tokens(messages)
 
         # Layer 3: hard collapse - last resort
         if current > self._collapse_at and len(messages) > 4:
@@ -169,7 +168,8 @@ class ContextManager:
                     ],
                 )
                 return resp.content
-            except Exception:
+            except Exception:  # noqa: BLE001, S110
+                # summarization is best-effort; fall back to extraction below
                 pass
 
         # fallback: extract key lines

corecoder-0.4.1/corecoder/demo.py

@@ -0,0 +1,84 @@
+"""Offline scripted demo: watch the full agent loop with no API key.
+
+Runs one scripted task through the real Agent loop with a ScriptedLLM, so the
+thought -> tool call -> observation cycle renders exactly as it would against
+a live model. Useful for demos, screenshots, and as a smoke test of the loop.
+"""
+
+import tempfile
+from pathlib import Path
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from .agent import Agent
+from .llm import LLMResponse, ScriptedLLM, ToolCall
+
+console = Console()
+
+_TASK = (
+    "Write a Python function `fib(n)` in fib.py returning the nth Fibonacci "
+    "number, add a pytest file, then run the tests."
+)
+
+
+def _script(workdir: Path) -> list[LLMResponse]:
+    fib_py = (
+        "def fib(n):\n"
+        "    if n < 2:\n"
+        "        return n\n"
+        "    a, b = 0, 1\n"
+        "    for _ in range(2, n + 1):\n"
+        "        a, b = b, a + b\n"
+        "    return b\n"
+    )
+    test_py = (
+        "from fib import fib\n"
+        "\n"
+        "def test_fib():\n"
+        "    assert fib(0) == 0\n"
+        "    assert fib(1) == 1\n"
+        "    assert fib(10) == 55\n"
+    )
+    return [
+        LLMResponse(
+            content="I'll write fib.py with an iterative implementation.",
+            tool_calls=[ToolCall(id="c1", name="write_file", arguments={"file_path": str(workdir / "fib.py"), "content": fib_py})],
+        ),
+        LLMResponse(
+            content="Now the test file covering the base cases and fib(10).",
+            tool_calls=[ToolCall(id="c2", name="write_file", arguments={"file_path": str(workdir / "test_fib.py"), "content": test_py})],
+        ),
+        LLMResponse(
+            content="Running the tests.",
+            tool_calls=[ToolCall(id="c3", name="bash", arguments={"command": f"cd {workdir} && python -m pytest test_fib.py -q"})],
+        ),
+        LLMResponse(
+            content="All three assertions pass. `fib` is iterative, and the test covers the base cases plus fib(10) == 55."
+        ),
+    ]
+
+
+def _summarize(args: dict) -> str:
+    parts = []
+    for key, value in args.items():
+        text = str(value)
+        if len(text) > 60:
+            text = text[:57] + "..."
+        parts.append(f"{key}={text}")
+    return " ".join(parts)
+
+
+def run_demo() -> int:
+    workdir = Path(tempfile.mkdtemp(prefix="corecoder-demo-"))
+    agent = Agent(llm=ScriptedLLM(_script(workdir)))
+
+    console.print(Panel.fit(f"[bold]{_TASK}[/]", title="corecoder demo (offline)"))
+    result = agent.chat(
+        _TASK,
+        on_tool=lambda name, args: console.print(f"[cyan]tool:[/] {name} {_summarize(args)}"),
+    )
+    console.print(Panel.fit(Markdown(result), title="final"))
+    console.print(f"[dim]workspace kept at {workdir}[/]")
+    return 0