diff --git a/README.md b/README.md index a6d0781a4..c0d4f800e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # CoreCoder -**The nanoGPT of coding agents. A 1.4k-line engine inside 3,276 readable lines of pure Python: understand how a coding agent actually works, then fork your own.** +**The nanoGPT of coding agents. A 1.4k-line engine inside 3,292 readable lines of pure Python: understand how a coding agent actually works, then fork your own.** *learn from it · fork it · ship something better* @@ -12,7 +12,7 @@ [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org) [![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) -[![engine](https://img.shields.io/badge/engine-1483_LoC-blue)](article/00-index_EN.md) +[![engine](https://img.shields.io/badge/engine-1496_LoC-blue)](article/00-index_EN.md) [![essays](https://img.shields.io/badge/source--reading-8_bilingual-orange)](article/00-index_EN.md) @@ -25,7 +25,7 @@ | | CoreCoder | Claude Code | aider | nanoGPT | |---|---|---|---|---| -| Lines of code | ~1,483 engine / 3,276 total | hundreds of thousands (closed) | tens of thousands of Python | ~600 (two files) | +| Lines of code | ~1,496 engine / 3,292 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 | @@ -36,9 +36,9 @@ The nanoGPT column is there as a reference point: minimal, readable, but it teac 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,483 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,276 physical lines, 2,703 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below. +The engine (loop, model interface, context, tools, sessions) is 1,496 lines once you drop blank lines and comments. Counting the outer CLI, config and packaging too, the whole package is 26 files: 3,292 physical lines, 2,716 net, every one short enough to read in a single sitting. The growth since the original 1,161-line snapshot went into visible features: plan mode, hooks and checkpoints, each documented below. -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. Anything that would mutate your disk or run a command stops for your consent first. The suite has 353 offline tests and an opt-in live smoke test. 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. Anything that would mutate your disk or run a command stops for your consent first. The suite has 356 offline tests and an opt-in live smoke test. 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. @@ -105,7 +105,7 @@ corecoder/ ├── demo.py offline end-to-end demo 101 lines └── tools/ ├── bash.py shell + dangerous-command gate + cd 203 lines - ├── edit.py unique-match search/replace + diff 99 lines + ├── edit.py unique-match search/replace + diff 115 lines ├── grep.py content search 93 lines ├── glob_tool.py filename matching 52 lines ├── read.py file read 56 lines diff --git a/README_CN.md b/README_CN.md index 69829ce6c..3c7d5718f 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,7 +2,7 @@ # CoreCoder -**编程 agent 里的 nanoGPT。1.4k 行引擎、整包 3276 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。** +**编程 agent 里的 nanoGPT。1.4k 行引擎、整包 3292 行纯 Python 全部一口气可读,读懂一个 coding agent 到底怎么运作,再 fork 出你自己的。** *learn from it · fork it · ship something better* @@ -12,7 +12,7 @@ [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org) [![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) -[![engine](https://img.shields.io/badge/engine-1483_LoC-blue)](article/) +[![engine](https://img.shields.io/badge/engine-1496_LoC-blue)](article/) [![源码导读](https://img.shields.io/badge/源码导读-8篇双语-orange)](article/) @@ -25,7 +25,7 @@ | | CoreCoder | Claude Code | aider | nanoGPT | |---|---|---|---|---| -| 代码量 | 引擎约 1483 行 / 整包 3276 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) | +| 代码量 | 引擎约 1496 行 / 整包 3292 行 | 几十万行(闭源) | 数万行 Python | 约 600 行(两个文件) | | 读完要多久 | 一个下午 | 读不了(闭源) | 得啃几天 | 一个下午 | | 能不能下断点改了再跑 | 能,每一行 | 不能 | 能,但量大 | 能 | | 定位 | 读懂并 fork 出你自己的 agent | 生产级编程助手 | 终端结对编程 | 教学用最小 GPT | @@ -36,9 +36,9 @@ nanoGPT 那一列是拿来对照的:它最小、可读,但教的是训一个 我一直觉得 coding agent 被讲得太玄了。把 Claude Code、Cursor 这类工具扒到底,核心是一个 while 循环套着一个大模型,外加七八个让它能真正动手的工具。难的从来不是这个循环,而是循环跑进真实世界以后要兜的那些底。CoreCoder 就是把这个核心老老实实写出来的最小版本。 -引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1483 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3276 行、净 2703 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。 +引擎部分(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1496 行。连最外层的 CLI、配置、打包一起算,整个包 26 个文件、物理 3292 行、净 2716 行,每个文件都短到能一口气读完。自 1161 行快照之后的增长都花在了看得见的功能上:plan mode、hooks、checkpoints,下文各有交代。 -它真能跑:读写文件、执行 shell、派子 agent、分三层压上下文,还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用,都会先停下来等你点头。现在有 353 个离线测试,另有按需开启的真实 API 冒烟。但能跑不是为了劝你拿去日用,而是为了让这份「注释」不撒谎:一个解释 agent 怎么运作的范例,自己得真能运作。 +它真能跑:读写文件、执行 shell、派子 agent、分三层压上下文,还能随时把这趟烧掉的 token 和美元数报给你。任何要动你磁盘、要跑命令的调用,都会先停下来等你点头。现在有 356 个离线测试,另有按需开启的真实 API 冒烟。但能跑不是为了劝你拿去日用,而是为了让这份「注释」不撒谎:一个解释 agent 怎么运作的范例,自己得真能运作。 代码来自一次公开拆解。公开的源码分析里,Claude Code 这类生产级 agent 暴露出不少关键架构,我挑出最核心的一层,用尽量少的代码诚实地复写了一遍。所以读 CoreCoder,约等于读一份基于公开源码分析的「可运行注释版」:讲的是这类 agent 的核心思路,而它本身只是最小复写,就摆在你机器上,随你拆、随你改。 @@ -105,7 +105,7 @@ corecoder/ ├── demo.py 离线端到端演示 101 行 └── tools/ ├── bash.py shell + 危险命令闸 + cd 追踪 203 行 - ├── edit.py 唯一匹配搜索替换 + diff 99 行 + ├── edit.py 唯一匹配搜索替换 + diff 115 行 ├── grep.py 内容搜索 93 行 ├── glob_tool.py 文件名匹配 52 行 ├── read.py 文件读取 56 行 diff --git a/article/00-index.md b/article/00-index.md index 1987dc02c..2fd2b640b 100644 --- a/article/00-index.md +++ b/article/00-index.md @@ -8,7 +8,7 @@ 因为 Claude Code 本体太大了。它的代码量在几十万行的量级,光一个负责跑 shell 命令的 BashTool 就上千行,真要逐行读完,多数人会在第三个文件就关掉编辑器。可 agent 的核心其实没那么复杂,复杂的是工程化之后那些为真实世界兜底的边角:模型半路被打断怎么办、上下文塞满了怎么办、十个工具调用同时回来怎么办、provider 偶尔抽风返回 500 又怎么办。这些东西摊在几十万行里,你很难一眼看到骨架。 -CoreCoder 做的事,是把这套骨架压到一千四百行出头的纯 Python。准确说,agent 引擎(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1483 行;连最外层的 CLI 终端、配置和打包都算上,整个包去掉空行和注释 2703 行,物理代码 3276 行。每个文件都短到能一口气读完,跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策,拣出最核心的那版,用最少的代码诚实地写一遍。 +CoreCoder 做的事,是把这套骨架压到一千四百行出头的纯 Python。准确说,agent 引擎(循环、模型接口、上下文、工具、会话)去掉空行和注释是 1496 行;连最外层的 CLI 终端、配置和打包都算上,整个包去掉空行和注释 2716 行,物理代码 3292 行。每个文件都短到能一口气读完,跑起来又确实是个能改代码、能跑命令、能自己开子任务、能压缩上下文、能算钱的 agent。它不是玩具。它是把生产级 agent 的每个设计决策,拣出最核心的那版,用最少的代码诚实地写一遍。 读它,约等于读一份 Claude Code 的「可运行注释版」。区别在于,CoreCoder 的每一行你都能在自己机器上断点、改、跑、看它出什么效果。本系列里我引用的每一个行数、每一段代码,都是从仓库里现读现核的,不是凭印象。这点我后面会反复较真,因为编码 agent 这个领域,太多文章在凭感觉编数字。 diff --git a/article/00-index_EN.md b/article/00-index_EN.md index a9569d8c6..4296f8c83 100644 --- a/article/00-index_EN.md +++ b/article/00-index_EN.md @@ -8,7 +8,7 @@ First, use CoreCoder, an open source project whose core runs to just over fourte Because Claude Code itself is too big. Its codebase runs into the hundreds of thousands of lines, and the BashTool alone, the part that runs shell commands, is over a thousand. Read it line by line and most people close the editor by the third file. Yet the core of an agent isn't really that complicated. What's complicated is everything engineered around it to survive the real world: what to do when the model gets interrupted mid-stream, when the context window fills up, when ten tool calls come back at once, when a provider hiccups and returns a 500. Spread across hundreds of thousands of lines, that skeleton is hard to see. -What CoreCoder does is squeeze the skeleton down to just over fourteen hundred lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1,483 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 2,703 lines without blanks and comments, 3,276 physical. Every file is short enough to read in one sitting, and what runs is genuinely an agent: it edits code, runs commands, spins up its own subtasks, compresses context, tracks cost. It is not a toy. It takes every design decision a production agent makes, picks the most essential version of each, and writes it out honestly in the least code it can. +What CoreCoder does is squeeze the skeleton down to just over fourteen hundred lines of pure Python. To be precise, the agent engine (the loop, model interface, context, tools, session) is 1,496 lines once you drop blank lines and comments; add the outermost CLI terminal, config, and packaging and the whole package is 2,716 lines without blanks and comments, 3,292 physical. Every file is short enough to read in one sitting, and what runs is genuinely an agent: it edits code, runs commands, spins up its own subtasks, compresses context, tracks cost. It is not a toy. It takes every design decision a production agent makes, picks the most essential version of each, and writes it out honestly in the least code it can. Reading it is close to reading a runnable, annotated edition of Claude Code. The difference is that every line of CoreCoder is something you can breakpoint, change, run, and watch on your own machine. Every line count and every snippet I quote in this series is read straight out of the repository, not recalled from memory. I'll keep being pedantic about that, because in the coding-agent space far too many write-ups just make the numbers up. diff --git a/corecoder/tools/edit.py b/corecoder/tools/edit.py index e10798fd8..c69f2efea 100644 --- a/corecoder/tools/edit.py +++ b/corecoder/tools/edit.py @@ -7,6 +7,7 @@ """ import difflib +import os from pathlib import Path from typing import ClassVar @@ -53,9 +54,19 @@ def execute(self, file_path: str, old_string: str, new_string: str) -> str: return f"Error: {file_path} not found" try: - content = p.read_text(encoding="utf-8") + # newline="" reads the file's own line endings, untranslated + with p.open(encoding="utf-8", newline="") as f: + raw = f.read() except UnicodeDecodeError: return f"Error: {file_path} is not a UTF-8 text file (edit_file only edits text files)" + # match on LF text, as read_file shows it, then write back the + # file's most common line ending instead of the platform's + crlf = raw.count("\r\n") + counts = {"\n": raw.count("\n") - crlf, "\r\n": crlf, "\r": raw.count("\r") - crlf} + eol = max(counts, key=counts.get) if any(counts.values()) else os.linesep + content = raw.replace("\r\n", "\n").replace("\r", "\n") + old_string = old_string.replace("\r\n", "\n") + new_string = new_string.replace("\r\n", "\n") occurrences = content.count(old_string) if occurrences == 0: @@ -71,8 +82,13 @@ def execute(self, file_path: str, old_string: str, new_string: str) -> str: ) new_content = content.replace(old_string, new_string, 1) + if "\n" in old_string + new_string: + out = new_content.replace("\n", eol) + else: # one-line edit: every other byte stays as it was + out = raw.replace(old_string, new_string, 1) _record_checkpoint(p) - p.write_text(new_content, encoding="utf-8") + with p.open("w", encoding="utf-8", newline="") as f: + f.write(out) _changed_files.add(str(p)) # generate a unified diff so the user/LLM can see exactly what changed diff --git a/pyproject.toml b/pyproject.toml index 6dc09e7bf..e35d3397b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" [project] name = "corecoder" version = "0.12.0" -description = "Minimal AI coding agent (3,276 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)" +description = "Minimal AI coding agent (3,292 lines of Python) inspired by Claude Code. Works with any LLM. (formerly NanoCoder)" readme = "README.md" license = "MIT" requires-python = ">=3.10" diff --git a/tests/test_tools.py b/tests/test_tools.py index febdb3f2e..57b6ec10d 100644 --- a/tests/test_tools.py +++ b/tests/test_tools.py @@ -317,6 +317,36 @@ def test_edit_file_rejects_non_utf8(tmp_path): assert "not a UTF-8 text file" in r +def test_edit_file_keeps_crlf_line_endings(tmp_path): + """A CRLF file stays CRLF, and old_string matches typed with LF or CRLF.""" + edit = get_tool("edit_file") + path = tmp_path / "win.txt" + path.write_bytes(b"one\r\ntwo\r\nthree\r\n") + r = edit.execute(file_path=str(path), old_string="one\ntwo", new_string="1\n2\n2b") + assert r.startswith("Edited") + assert path.read_bytes() == b"1\r\n2\r\n2b\r\nthree\r\n" + r = edit.execute(file_path=str(path), old_string="2b\r\nthree", new_string="3") + assert r.startswith("Edited") + assert path.read_bytes() == b"1\r\n2\r\n3\r\n" + + +def test_edit_file_keeps_lf_line_endings(tmp_path): + """An LF file stays LF even where the platform default is CRLF.""" + edit = get_tool("edit_file") + path = tmp_path / "unix.txt" + path.write_bytes(b"a\nb\nc\n") + edit.execute(file_path=str(path), old_string="b", new_string="B\nB2") + assert path.read_bytes() == b"a\nB\nB2\nc\n" + + +def test_edit_file_one_line_edit_leaves_mixed_endings_alone(tmp_path): + edit = get_tool("edit_file") + path = tmp_path / "mixed.txt" + path.write_bytes(b"a\r\nb\nc\r\n") + edit.execute(file_path=str(path), old_string="b", new_string="B") + assert path.read_bytes() == b"a\r\nB\nc\r\n" + + # --- glob --- def test_glob_finds_files():